{ "openapi": "3.1.0", "info": { "title": "CrawlKit API", "description": "CrawlKit is an API-first data engineering platform for turning web pages, APIs, files, healthcare pricing data, and search/content signals into validated, queryable datasets. The API covers acquisition, spiders, scraping, structured extraction, Arrow/DataFusion query, ETL, enrichment, durable workflows, quality gates, lineage, OpenRate transparency data, SEO/GSC/DNS checks, and agent-ready operational intelligence.\n\n## Platform Capabilities\n\n- **Acquisition and spiders**: Crawl jobs, AI-assisted spider building, selector inspection, stealth/proxy status, and extraction tests\n- **Datasets and Arrow query**: Typed datasets, row import/export, Arrow IPC, Parquet/CSV/JSON exports, SQL, DataFusion, and hybrid query views\n- **ETL and durable workflows**: Reusable DAG templates, scheduled pipelines, run monitoring, queues, checkpoints, and workflow operations\n- **Enrichment and quality**: Source-driven enrichment, heuristic filters, duplicate detection, taxonomy classification, decontamination, and quality scorecards\n- **Lineage and governance**: Asset registration, upstream/downstream graphs, consent records, schema registry, artifacts, and provenance edges\n- **OpenRate healthcare pricing**: Rate search, comparisons, discrepancy analysis, source discovery, MRF/TiC ingestion, and materialized-view refreshes\n- **SEO, content, and search intelligence**: Site audits, URL checks, DNS/SSL/redirect checks, GSC integration, schema generation, content briefs, internal links, and SERP competitors\n- **Operational intelligence**: Alerts, measurement experiments, scoring, forecasts, causal analysis, leads, social monitoring, and pipeline/revenue context\n\n## Authentication\n\nAll authenticated endpoints require a Bearer token in the `Authorization` header.\nTwo auth methods are supported:\n\n- **Session JWT**: `Authorization: Bearer `\n- **API Key**: `Authorization: Bearer ck_live_*`\n\n## Access Model\n\nEndpoints are grouped by capability domain and enforced with account, role, and plan checks. Higher-throughput crawls, enrichment jobs, workflow execution, intelligence operations, and agency/multi-site features may require elevated access.", "contact": { "name": "CrawlKit", "url": "https://crawlkit.app" }, "license": { "name": "Proprietary" }, "version": "0.2.0" }, "servers": [ { "url": "https://api.crawlkit.app", "description": "Production" }, { "url": "http://localhost:3001", "description": "Local development" } ], "paths": { "/api/v1/alerts": { "get": { "tags": [ "Alerts" ], "operationId": "list", "parameters": [ { "name": "alert_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "dismissed", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List alerts for account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/alerts/:id/dismiss": { "put": { "tags": [ "Alerts" ], "operationId": "dismiss", "parameters": [ { "name": "id", "in": "path", "description": "Notification ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Alert dismissed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DismissResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/alerts/insights": { "get": { "tags": [ "Alerts" ], "operationId": "insights", "responses": { "200": { "description": "Graphiti-powered alert insights (Pro)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertInsightsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/alerts/settings": { "get": { "tags": [ "Alerts" ], "operationId": "get_settings", "responses": { "200": { "description": "Notification settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettingsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Alerts" ], "operationId": "update_settings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationSettingsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/analysis/quality-pipeline": { "post": { "tags": [ "Analysis" ], "summary": "Trigger quality pipeline workflow", "description": "Triggers the autonomous Crawl -> Quality -> Scoring pipeline (Flow A). The workflow crawls, analyzes, classifies, quality-filters, scores, creates lineage, and updates the intelligence graph.", "operationId": "trigger_quality_pipeline", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityPipelineRequest" } } }, "required": true }, "responses": { "200": { "description": "Quality pipeline triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QualityPipelineResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/artifacts": { "get": { "tags": [ "Artifacts" ], "summary": "List artifacts", "description": "List artifacts with optional filters.", "operationId": "list_artifacts", "parameters": [ { "name": "site_url", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of artifacts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ArtifactResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Artifacts" ], "summary": "Register artifact", "description": "Register a new artifact from a source URL.", "operationId": "register_artifact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterArtifactRequest" } } }, "required": true }, "responses": { "201": { "description": "Artifact registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/artifacts/:artifact_id": { "get": { "tags": [ "Artifacts" ], "summary": "Get artifact", "description": "Get an artifact by ID.", "operationId": "get_artifact", "parameters": [ { "name": "artifact_id", "in": "path", "description": "Artifact ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Artifact details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Artifacts" ], "summary": "Delete artifact", "description": "Delete an artifact and its S3 object if present.", "operationId": "delete_artifact", "parameters": [ { "name": "artifact_id", "in": "path", "description": "Artifact ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Artifact deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/artifacts/:artifact_id/download": { "post": { "tags": [ "Artifacts" ], "summary": "Download artifact", "description": "Download artifact from source URL to object store.", "operationId": "download_artifact", "parameters": [ { "name": "artifact_id", "in": "path", "description": "Artifact ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Download initiated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactDownloadResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Object store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/artifacts/:artifact_id/url": { "get": { "tags": [ "Artifacts" ], "summary": "Get artifact URL", "description": "Get a presigned URL for downloading an artifact.", "operationId": "get_artifact_url", "parameters": [ { "name": "artifact_id", "in": "path", "description": "Artifact ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Presigned URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArtifactUrlResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Object store unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/assets/definitions": { "get": { "tags": [ "Asset Definitions" ], "operationId": "list_definitions", "parameters": [ { "name": "asset_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List asset definitions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetDefinitionResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Asset Definitions" ], "operationId": "create_definition", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetDefinitionRequest" } } }, "required": true }, "responses": { "200": { "description": "Created asset definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDefinitionResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/assets/definitions/{id}": { "get": { "tags": [ "Asset Definitions" ], "operationId": "get_definition", "parameters": [ { "name": "id", "in": "path", "description": "Asset definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get asset definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDefinitionResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Asset Definitions" ], "operationId": "update_definition", "parameters": [ { "name": "id", "in": "path", "description": "Asset definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetDefinitionRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated asset definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDefinitionResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Asset Definitions" ], "operationId": "delete_definition", "parameters": [ { "name": "id", "in": "path", "description": "Asset definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted asset definition" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/audit": { "post": { "tags": [ "Audit" ], "summary": "Real-time site audit (SSE)", "description": "Crawl a site, analyze for SEO issues, and stream results in real-time via Server-Sent Events. Public endpoint with visitor-based rate limiting (no auth required).\n\nSSE event types: `rate_info`, `crawl_started`, `page_crawled`, `issue_found`, `audit_complete`, `error`.", "operationId": "handle_audit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditRequest" } } }, "required": true }, "responses": { "200": { "description": "SSE stream of audit events (crawl_started, page_crawled, issue_found, audit_complete)", "content": { "text/event-stream": {} } }, "400": { "description": "Invalid URL", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "Rate limited" } } } }, "/api/v1/audit/run": { "post": { "tags": [ "Analysis" ], "summary": "Run authenticated audit with persistence", "description": "Crawl a site, analyze for SEO issues, persist results to the database, and return the full analysis. Unlike the SSE audit endpoint, this returns a single JSON response after completion.", "operationId": "run_audit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Audit completed and persisted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "400": { "description": "Invalid URL" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/audits": { "get": { "tags": [ "Analysis" ], "operationId": "list_audits", "parameters": [ { "name": "site_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List audits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/audits/:audit_id": { "get": { "tags": [ "Analysis" ], "operationId": "get_audit", "parameters": [ { "name": "audit_id", "in": "path", "description": "Audit ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get audit details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditDetailResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/auth/tenants/provision": { "post": { "tags": [ "Auth" ], "summary": "Provision tenant", "description": "Provision a new tenant account, enterprise usage row, optional site/custom-domain records, and a full-access API key. The plaintext API key is returned once in the response.", "operationId": "provision_tenant", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionTenantRequest" } } }, "required": true }, "responses": { "200": { "description": "Tenant provisioned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionTenantResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Full-access key required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/auth/tokens": { "get": { "tags": [ "Auth" ], "summary": "List tenant API tokens", "description": "List API tokens for the selected CrawlKit tenant account. Only prefixes and metadata are returned.", "operationId": "list_tokens", "parameters": [ { "name": "account_id", "in": "query", "description": "Tenant account id. Defaults to the authenticated request account.", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Tenant API tokens", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTokenSummary" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Auth" ], "summary": "Create tenant API token", "description": "Create a tenant-scoped API token. The plaintext token is returned once and only the SHA-256 hash is stored.", "operationId": "create_token", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenRequest" } } }, "required": true }, "responses": { "200": { "description": "Created tenant API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiTokenResponse" } } } }, "400": { "description": "Invalid token request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/auth/tokens/{token_id}": { "delete": { "tags": [ "Auth" ], "summary": "Delete tenant API token", "description": "Revoke a tenant-scoped API token by deleting its hashed record.", "operationId": "delete_token", "parameters": [ { "name": "token_id", "in": "path", "description": "API token ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "account_id", "in": "query", "description": "Tenant account id. Defaults to the authenticated request account.", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Deleted tenant API token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteApiTokenResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/auth/usage": { "get": { "tags": [ "Auth" ], "summary": "Get usage summary", "description": "Get the current account's usage summary including checks and audits consumed.", "operationId": "usage", "responses": { "200": { "description": "Current usage summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageSummary" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/auth/validate": { "post": { "tags": [ "Auth" ], "summary": "Validate API key", "description": "Validate an API key and return the associated tenant account, tier, scopes, and current usage summary.", "operationId": "validate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateRequest" } } }, "required": true }, "responses": { "200": { "description": "API key validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateResponse" } } } }, "401": { "description": "Invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/brief": { "post": { "tags": [ "Content" ], "operationId": "brief", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefRequest" } } }, "required": true }, "responses": { "200": { "description": "Generate content brief", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - insufficient tier" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/briefs": { "get": { "tags": [ "Content" ], "operationId": "list_briefs", "parameters": [ { "name": "site_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List content briefs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/briefs/:brief_id": { "get": { "tags": [ "Content" ], "operationId": "get_brief", "parameters": [ { "name": "brief_id", "in": "path", "description": "Brief ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get brief details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefDetailResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Content" ], "operationId": "update_brief", "parameters": [ { "name": "brief_id", "in": "path", "description": "Brief ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBriefRequest" } } }, "required": true }, "responses": { "200": { "description": "Brief updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BriefDetailResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Content" ], "operationId": "delete_brief", "parameters": [ { "name": "brief_id", "in": "path", "description": "Brief ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Brief deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteBriefResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/campaigns": { "get": { "tags": [ "Leads" ], "summary": "List campaigns", "operationId": "list_campaigns", "responses": { "200": { "description": "List of campaigns", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Leads" ], "summary": "Create a campaign", "operationId": "create_campaign", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCampaignRequest" } } }, "required": true }, "responses": { "201": { "description": "Campaign created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/campaigns/:id": { "get": { "tags": [ "Leads" ], "summary": "Get a campaign", "operationId": "get_campaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Campaign details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/campaigns/:id/advance": { "post": { "tags": [ "Leads" ], "summary": "Advance leads in a campaign", "operationId": "advance_campaign", "parameters": [ { "name": "id", "in": "path", "description": "Campaign ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceCampaignRequest" } } }, "required": true }, "responses": { "200": { "description": "Leads advanced", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceCampaignResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/check": { "post": { "tags": [ "Analysis" ], "operationId": "check_content", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckContentRequest" } } }, "required": true }, "responses": { "200": { "description": "Check HTML content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/check-url": { "post": { "tags": [ "Analysis" ], "operationId": "check_url", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "Check URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/clients": { "get": { "tags": [ "Clients" ], "operationId": "list", "responses": { "200": { "description": "List agency client accounts with stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Clients" ], "operationId": "add", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddClientRequest" } } }, "required": true }, "responses": { "200": { "description": "Client added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientDto" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/clients/:client_id": { "get": { "tags": [ "Clients" ], "operationId": "detail", "parameters": [ { "name": "client_id", "in": "path", "description": "Client account ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Client detail with sites and health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientDetailResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Clients" ], "operationId": "remove", "parameters": [ { "name": "client_id", "in": "path", "description": "Client account ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Client removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveClientResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/competitors": { "get": { "tags": [ "Content" ], "operationId": "competitors", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Analyze SERP competitors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorAnalysis" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - insufficient tier" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/ai/generate": { "post": { "tags": [ "Content Workspace" ], "summary": "AI content generation", "operationId": "ai_generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiGenerateRequest" } } }, "required": true }, "responses": { "200": { "description": "Generated content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiGenerateResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/ai/rewrite": { "post": { "tags": [ "Content Workspace" ], "summary": "AI content rewrite", "operationId": "ai_rewrite", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRewriteRequest" } } }, "required": true }, "responses": { "200": { "description": "Rewritten content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiRewriteResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/calendar": { "get": { "tags": [ "Content Workspace" ], "summary": "Get publishing calendar", "operationId": "calendar", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } } ], "responses": { "200": { "description": "Publishing calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents": { "get": { "tags": [ "Content Workspace" ], "summary": "List content documents", "operationId": "list_documents", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Document list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Content Workspace" ], "summary": "Create content document", "operationId": "create_document", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDocumentRequest" } } }, "required": true }, "responses": { "201": { "description": "Document created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents/:id/approval-status": { "get": { "tags": [ "Content Workspace" ], "summary": "Get document approval status", "description": "Inspect the editorial approval status for a content document.", "operationId": "get_approval_status", "parameters": [ { "name": "id", "in": "path", "description": "Content document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approval status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Approval not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents/:id/approve": { "post": { "tags": [ "Content Workspace" ], "summary": "Approve document", "description": "Approve a content document in the editorial approval workflow.", "operationId": "approve_document", "parameters": [ { "name": "id", "in": "path", "description": "Content document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Approval accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Approval not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents/:id/reject": { "post": { "tags": [ "Content Workspace" ], "summary": "Reject document approval", "description": "Reject a content document approval request with reviewer feedback.", "operationId": "reject_approval", "parameters": [ { "name": "id", "in": "path", "description": "Content document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectApprovalRequest" } } }, "required": true }, "responses": { "200": { "description": "Approval rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Approval not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents/:id/request-approval": { "post": { "tags": [ "Content Workspace" ], "summary": "Request document approval", "description": "Create an approval request for a content document before publication or workflow handoff.", "operationId": "request_approval", "parameters": [ { "name": "id", "in": "path", "description": "Content document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestApprovalRequest" } } }, "required": true }, "responses": { "200": { "description": "Approval requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents/{id}": { "get": { "tags": [ "Content Workspace" ], "summary": "Get content document", "operationId": "get_document", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Content Workspace" ], "summary": "Update content document", "operationId": "update_document", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDocumentRequest" } } }, "required": true }, "responses": { "200": { "description": "Document updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/documents/{id}/publish": { "post": { "tags": [ "Content Workspace" ], "summary": "Publish content document", "operationId": "publish_document", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishRequest" } } }, "required": true }, "responses": { "200": { "description": "Document published", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/content/extract": { "post": { "tags": [ "Content" ], "summary": "Extract article content from a URL", "operationId": "extract_content_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentExtractionRequest" } } }, "required": true }, "responses": { "200": { "description": "Extracted content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentExtractionResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/cost/record": { "post": { "tags": [ "Cost Attribution" ], "operationId": "create_record", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCostRecordRequest" } } }, "required": true }, "responses": { "200": { "description": "Cost record created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CostRecordResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/cost/records": { "get": { "tags": [ "Cost Attribution" ], "operationId": "list_records", "parameters": [ { "name": "pipeline_run_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "resource_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List cost records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CostRecordResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/cost/summary": { "get": { "tags": [ "Cost Attribution" ], "operationId": "get_summary", "parameters": [ { "name": "resource_type", "in": "query", "description": "Filter by resource type", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cost summary by resource type", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CostSummaryResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/frontier/:job_id": { "get": { "tags": [ "Crawl" ], "summary": "Get frontier stats", "description": "Get URL frontier statistics for a running or completed crawl job.", "operationId": "get_frontier_stats", "parameters": [ { "name": "job_id", "in": "path", "description": "Crawl job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Frontier statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrontierStatsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/jobs": { "get": { "tags": [ "Crawl" ], "summary": "List crawl jobs", "description": "List crawl jobs for a site with optional status filter.", "operationId": "list_jobs", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of crawl jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Crawl" ], "summary": "Create crawl job", "description": "Create a new distributed crawl job. Triggers the DistributedCrawlWorkflow via Restate.", "operationId": "create_job", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateJobRequest" } } }, "required": true }, "responses": { "201": { "description": "Crawl job created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/jobs/:job_id": { "get": { "tags": [ "Crawl" ], "summary": "Get crawl job", "description": "Get the current status and progress of a crawl job.", "operationId": "get_job", "parameters": [ { "name": "job_id", "in": "path", "description": "Crawl job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Crawl job details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/jobs/:job_id/cancel": { "post": { "tags": [ "Crawl" ], "summary": "Cancel crawl job", "description": "Cancel a crawl job. Cannot cancel completed, failed, or already cancelled jobs.", "operationId": "cancel_job", "parameters": [ { "name": "job_id", "in": "path", "description": "Crawl job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActionResponse" } } } }, "400": { "description": "Job already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/jobs/:job_id/pause": { "post": { "tags": [ "Crawl" ], "summary": "Pause crawl job", "description": "Pause a running crawl job. Only valid for seeding, crawling, or analyzing jobs.", "operationId": "pause_job", "parameters": [ { "name": "job_id", "in": "path", "description": "Crawl job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActionResponse" } } } }, "400": { "description": "Invalid state transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/jobs/:job_id/resume": { "post": { "tags": [ "Crawl" ], "summary": "Resume crawl job", "description": "Resume a paused crawl job.", "operationId": "resume_job", "parameters": [ { "name": "job_id", "in": "path", "description": "Crawl job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Job resumed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobActionResponse" } } } }, "400": { "description": "Job not paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/proxies": { "get": { "tags": [ "Crawl" ], "summary": "List proxies", "description": "List all proxy endpoints configured for the account with health metrics.", "operationId": "list_proxies", "responses": { "200": { "description": "List of proxy endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProxyListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/sitemap/discover": { "post": { "tags": [ "Crawl" ], "summary": "Discover sitemaps", "description": "Synchronously discover and parse sitemaps for a site URL (via robots.txt and well-known locations) or parse a sitemap URL directly. Child sitemaps in an index are reported but not expanded.", "operationId": "discover_sitemaps", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitemapDiscoverRequest" } } }, "required": true }, "responses": { "200": { "description": "Discovered sitemaps with entry counts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitemapDiscoverResponse" } } } }, "400": { "description": "Invalid or unsafe URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/crawl/strategies": { "get": { "tags": [ "Crawl" ], "summary": "List crawl strategies", "description": "List all named crawl strategies for the account.", "operationId": "list_strategies", "responses": { "200": { "description": "List of strategies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Crawl" ], "summary": "Create crawl strategy", "description": "Create a reusable named crawl strategy with custom exploration parameters.", "operationId": "create_strategy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateStrategyRequest" } } }, "required": true }, "responses": { "201": { "description": "Strategy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StrategyResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/dashboard": { "get": { "tags": [ "Dashboard" ], "operationId": "overview", "responses": { "200": { "description": "Dashboard overview for account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets": { "get": { "tags": [ "Datasets" ], "summary": "List datasets", "description": "List datasets with optional status/search filters.", "operationId": "list_datasets", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of datasets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Datasets" ], "summary": "Create dataset", "description": "Create a new dataset with a column schema.", "operationId": "create_dataset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetRequest" } } }, "required": true }, "responses": { "201": { "description": "Dataset created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets/:dataset_id": { "get": { "tags": [ "Datasets" ], "summary": "Get dataset", "description": "Get a dataset by ID.", "operationId": "get_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dataset details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Datasets" ], "summary": "Update dataset", "description": "Update an existing dataset's metadata or schema.", "operationId": "update_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetRequest" } } }, "required": true }, "responses": { "200": { "description": "Dataset updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Datasets" ], "summary": "Delete dataset", "description": "Delete a dataset and all its rows.", "operationId": "delete_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Dataset deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets/:dataset_id/export": { "post": { "tags": [ "Datasets" ], "summary": "Export dataset", "description": "Export dataset rows with optional column filtering.", "operationId": "export_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRequest" } } }, "required": true }, "responses": { "200": { "description": "Export result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dataset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets/:dataset_id/import": { "post": { "tags": [ "Datasets" ], "summary": "Import data", "description": "Import rows into a dataset from JSON data.", "operationId": "import_dataset", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportDatasetRequest" } } }, "required": true }, "responses": { "200": { "description": "Import result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRowResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dataset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets/:dataset_id/rows": { "get": { "tags": [ "Datasets" ], "summary": "List rows", "description": "List rows in a dataset with pagination.", "operationId": "list_rows", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "columns", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List of rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RowListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dataset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Datasets" ], "summary": "Create row", "description": "Add a row to a dataset.", "operationId": "create_row", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRowRequest" } } }, "required": true }, "responses": { "201": { "description": "Row created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRowResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dataset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets/:dataset_id/rows/:row_id": { "put": { "tags": [ "Datasets" ], "summary": "Update row", "description": "Update a row's data in a dataset.", "operationId": "update_row", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "row_id", "in": "path", "description": "Row ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRowRequest" } } }, "required": true }, "responses": { "200": { "description": "Row updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetRowResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Datasets" ], "summary": "Delete row", "description": "Delete a row from a dataset.", "operationId": "delete_row", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "row_id", "in": "path", "description": "Row ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Row deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/datasets/:dataset_id/stats": { "get": { "tags": [ "Datasets" ], "summary": "Dataset stats", "description": "Get row count, column count, enrichment coverage, and source breakdown.", "operationId": "dataset_stats", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dataset statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetStatsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Dataset not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/dns/audit": { "post": { "tags": [ "DNS" ], "operationId": "audit_dns", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsAuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Full DNS audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DnsAuditResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/dns/email-auth": { "post": { "tags": [ "DNS" ], "summary": "Check email authentication", "operationId": "check_email_auth", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAuthCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Email auth check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailAuthDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/dns/redirects": { "post": { "tags": [ "DNS" ], "summary": "Trace redirect chain", "operationId": "trace_redirects", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Redirect chain", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RedirectDto" } } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/dns/ssl": { "post": { "tags": [ "DNS" ], "summary": "Validate SSL/TLS certificate", "operationId": "validate_ssl", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SslCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "SSL check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SslDto" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/domains": { "get": { "tags": [ "Clients" ], "operationId": "list_domains", "responses": { "200": { "description": "List custom domains", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DomainListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Clients" ], "operationId": "add_domain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddDomainRequest" } } }, "required": true }, "responses": { "200": { "description": "Domain added with CNAME instructions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomDomainDto" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/domains/:domain_id": { "delete": { "tags": [ "Clients" ], "operationId": "delete_domain", "parameters": [ { "name": "domain_id", "in": "path", "description": "Domain ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDomainResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/domains/:domain_id/status": { "get": { "tags": [ "Clients" ], "operationId": "domain_status", "parameters": [ { "name": "domain_id", "in": "path", "description": "Domain ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Domain verification status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomDomainDto" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/enrichment/enrich": { "post": { "tags": [ "Enrichment" ], "summary": "Enrich rows", "description": "Start an enrichment job to enrich dataset rows using a specified source.", "operationId": "enrich", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichRequest" } } }, "required": true }, "responses": { "202": { "description": "Enrichment job started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/enrichment/jobs/:job_id": { "get": { "tags": [ "Enrichment" ], "summary": "Job status", "description": "Get the status and progress of an enrichment job.", "operationId": "job_status", "parameters": [ { "name": "job_id", "in": "path", "description": "Enrichment job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Enrichment job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichmentStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Job not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/enrichment/sources": { "get": { "tags": [ "Enrichment" ], "summary": "List sources", "description": "List all available enrichment sources with capabilities and rate limits.", "operationId": "list_sources", "responses": { "200": { "description": "List of enrichment sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourceListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/compress": { "post": { "tags": [ "ETL" ], "summary": "Compress or decompress", "description": "Compress or decompress a file in object store.", "operationId": "compress", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompressRequest" } } }, "required": true }, "responses": { "200": { "description": "Operation completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompressResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/fetch": { "post": { "tags": [ "ETL" ], "summary": "Fetch remote artifact", "description": "Download a remote file into tenant object store.", "operationId": "fetch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchRequest" } } }, "required": true }, "responses": { "200": { "description": "Fetch completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FetchResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/load": { "post": { "tags": [ "ETL" ], "summary": "Bulk load Parquet to PostgreSQL", "description": "COPY-load Parquet partitions into a PostgreSQL table.", "operationId": "load", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadRequest" } } }, "required": true }, "responses": { "200": { "description": "Load completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoadResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/parse": { "post": { "tags": [ "ETL" ], "summary": "Parse JSON/CSV to Parquet", "description": "Parse a JSON or CSV file from object store into Parquet partitions.", "operationId": "parse", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseRequest" } } }, "required": true }, "responses": { "200": { "description": "Parse completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ParseResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/pipelines": { "get": { "tags": [ "ETL" ], "summary": "List ETL pipelines", "description": "List ETL pipelines with optional status/search filters.", "operationId": "list_etl_pipelines", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "pipeline_kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of ETL pipelines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "ETL" ], "summary": "Create ETL pipeline", "description": "Create a new ETL pipeline with step definitions.", "operationId": "create_etl_pipeline", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEtlPipelineRequest" } } }, "required": true }, "responses": { "201": { "description": "ETL pipeline created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/pipelines/:pipeline_id": { "get": { "tags": [ "ETL" ], "summary": "Get ETL pipeline", "description": "Get an ETL pipeline by ID.", "operationId": "get_etl_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "ETL pipeline details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "ETL" ], "summary": "Update ETL pipeline", "description": "Update an existing ETL pipeline.", "operationId": "update_etl_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePipelineRequest" } } }, "required": true }, "responses": { "200": { "description": "ETL pipeline updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "ETL" ], "summary": "Delete ETL pipeline", "description": "Delete an ETL pipeline.", "operationId": "delete_etl_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "ETL pipeline deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/pipelines/:pipeline_id/run": { "post": { "tags": [ "ETL" ], "summary": "Run ETL pipeline", "description": "Start a new run of an ETL pipeline.", "operationId": "run_etl_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPipelineRequest" } } }, "required": true }, "responses": { "202": { "description": "ETL pipeline run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/pipelines/:pipeline_id/runs": { "get": { "tags": [ "ETL" ], "summary": "List ETL runs", "description": "List runs of an ETL pipeline.", "operationId": "list_etl_runs", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/runs/:run_id": { "get": { "tags": [ "ETL" ], "summary": "Get ETL run", "description": "Get an ETL pipeline run by ID.", "operationId": "get_etl_run_status", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/runs/:run_id/cancel": { "post": { "tags": [ "ETL" ], "summary": "Cancel ETL run", "description": "Cancel a running or paused ETL pipeline execution.", "operationId": "cancel_etl_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineActionResponse" } } } }, "400": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/etl/runs/:run_id/pause": { "post": { "tags": [ "ETL" ], "summary": "Pause ETL run", "description": "Pause a running ETL pipeline execution.", "operationId": "pause_etl_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineActionResponse" } } } }, "400": { "description": "Cannot pause", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/feedback/record": { "post": { "tags": [ "Feedback" ], "summary": "Record feedback event", "description": "Record a feedback loop event — issue detection, fix application, or verification result.", "operationId": "record", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordEventRequest" } } }, "required": true }, "responses": { "200": { "description": "Feedback loop event recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackLoopDto" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/feedback/stats": { "get": { "tags": [ "Feedback" ], "summary": "Get feedback stats", "description": "Get feedback loop statistics including success rate and resolution times.", "operationId": "stats", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Feedback loop statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedbackStatsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/feedback/status": { "get": { "tags": [ "Feedback" ], "summary": "Get pending verifications", "description": "Get feedback loops that are pending verification for a site.", "operationId": "pending", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pending feedback loops", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FeedbackLoopDto" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/governance/policies": { "get": { "tags": [ "Governance" ], "summary": "List governance policies", "operationId": "list_policies", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Policy list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Governance" ], "summary": "Create governance policy", "operationId": "create_policy", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePolicyRequest" } } }, "required": true }, "responses": { "201": { "description": "Policy created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/governance/policies/{id}": { "get": { "tags": [ "Governance" ], "summary": "Get governance policy", "operationId": "get_policy", "parameters": [ { "name": "id", "in": "path", "description": "Policy ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Policy details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/governance/policies/{id}/comment": { "post": { "tags": [ "Governance" ], "summary": "Comment on governance policy", "operationId": "comment_on_policy", "parameters": [ { "name": "id", "in": "path", "description": "Policy ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentRequest" } } }, "required": true }, "responses": { "201": { "description": "Comment added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyCommentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/governance/policies/{id}/review": { "post": { "tags": [ "Governance" ], "summary": "Review governance policy", "operationId": "review_policy", "parameters": [ { "name": "id", "in": "path", "description": "Policy ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewPolicyRequest" } } }, "required": true }, "responses": { "200": { "description": "Policy reviewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PolicyResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/governance/queue": { "get": { "tags": [ "Governance" ], "summary": "Get governance review queue", "operationId": "get_queue", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Governance queue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/graph/timeline": { "get": { "tags": [ "Graph" ], "summary": "Get a chronological event timeline for an entity in the temporal knowledge graph", "operationId": "get_timeline", "parameters": [ { "name": "entity", "in": "query", "description": "Entity to build a timeline for (name or search phrase).", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return (default 50, max 200).", "required": false, "schema": { "type": [ "integer", "null" ], "minimum": 0 } } ], "responses": { "200": { "description": "Chronological events for the entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No entity matched", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Graphiti sidecar not configured or unreachable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/analytics": { "post": { "tags": [ "GSC" ], "summary": "Search analytics", "operationId": "analytics", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsRequest" } } }, "required": true }, "responses": { "200": { "description": "Search analytics data", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/auth/callback": { "get": { "tags": [ "GSC" ], "summary": "Complete Google OAuth browser callback", "operationId": "browser_auth_callback", "parameters": [ { "name": "code", "in": "query", "description": "One-time authorization code returned by Google", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "description": "Opaque one-time state issued by CrawlKit", "required": false, "schema": { "type": "string" } }, { "name": "error", "in": "query", "description": "OAuth provider error when authorization was denied", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Google Search Console connected", "content": { "text/html": {} } }, "400": { "description": "Authorization invalid, expired, denied, or already used", "content": { "text/html": {} } } } }, "post": { "tags": [ "GSC" ], "summary": "OAuth callback", "operationId": "auth_callback", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCallbackRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth callback processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthCallbackResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/auth/client": { "get": { "tags": [ "GSC" ], "summary": "Get OAuth client configuration status", "operationId": "oauth_client_status", "responses": { "200": { "description": "Redacted OAuth client configuration status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientConfigStatus" } } } }, "403": { "description": "Admin settings permission required" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "GSC" ], "summary": "Configure tenant OAuth client", "operationId": "configure_oauth_client", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth client encrypted and configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthClientConfigStatus" } } } }, "400": { "description": "Invalid OAuth client configuration" }, "403": { "description": "Admin settings permission required" }, "503": { "description": "Credential encryption is not enabled" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/auth/url": { "post": { "tags": [ "GSC" ], "summary": "Get OAuth URL", "operationId": "auth_url", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "OAuth URL generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthUrlResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/index": { "post": { "tags": [ "GSC" ], "summary": "Submit URL for indexing", "operationId": "index_url", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexRequest" } } }, "required": true }, "responses": { "200": { "description": "URL indexing submission result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/index/remove": { "post": { "tags": [ "GSC" ], "summary": "Request URL removal", "operationId": "index_remove", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexRequest" } } }, "required": true }, "responses": { "200": { "description": "URL removal request result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/inspect": { "post": { "tags": [ "GSC" ], "summary": "Inspect URL", "operationId": "inspect", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectRequest" } } }, "required": true }, "responses": { "200": { "description": "URL inspection result", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/inspect/analyze": { "post": { "tags": [ "GSC" ], "summary": "Inspect and analyze URL", "operationId": "inspect_analyzed", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectRequest" } } }, "required": true }, "responses": { "200": { "description": "URL inspection with analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectionAnalysisResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/inspect/batch": { "post": { "tags": [ "GSC" ], "summary": "Batch inspect URLs", "operationId": "inspect_batch", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchInspectRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch URL inspection results", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/properties": { "get": { "tags": [ "GSC" ], "summary": "List GSC properties", "operationId": "list_properties", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of GSC properties", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/property": { "get": { "tags": [ "GSC" ], "summary": "Find GSC property", "operationId": "find_property", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "GSC property if found", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/sitemaps": { "get": { "tags": [ "GSC" ], "summary": "List sitemaps", "operationId": "sitemaps", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List of sitemaps", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/gsc/snapshot": { "get": { "tags": [ "GSC" ], "summary": "Get property snapshot", "operationId": "snapshot", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Property snapshot with aggregated metrics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GscSnapshotResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/healing/auto-heal": { "post": { "tags": [ "Healing" ], "summary": "Auto-heal pipeline", "description": "Attempt autonomous auto-healing of a failed pipeline run. Diagnoses the failure, checks auto-heal gate, and applies fix if confidence is high enough.", "operationId": "auto_heal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoHealRequest" } } }, "required": true }, "responses": { "200": { "description": "Auto-heal result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutoHealResult" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "LLM unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/healing/diagnose": { "post": { "tags": [ "Healing" ], "summary": "Diagnose pipeline", "description": "Use LLM to diagnose a pipeline failure and propose a configuration fix.", "operationId": "diagnose", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnoseRequest" } } }, "required": true }, "responses": { "200": { "description": "Diagnosis with proposed patch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiagnoseResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "LLM unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/healing/patches": { "get": { "tags": [ "Healing" ], "summary": "List patches", "description": "List LLM-proposed pipeline patches with optional filters.", "operationId": "list_patches", "parameters": [ { "name": "pipeline_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of patches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/healing/patches/:id": { "get": { "tags": [ "Healing" ], "summary": "Get patch", "description": "Get a pipeline patch by ID.", "operationId": "get_patch", "parameters": [ { "name": "id", "in": "path", "description": "Patch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Patch details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/healing/patches/:id/apply": { "post": { "tags": [ "Healing" ], "summary": "Apply patch", "description": "Apply an LLM-proposed patch to the target pipeline.", "operationId": "apply_patch", "parameters": [ { "name": "id", "in": "path", "description": "Patch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Patch applied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPatchResponse" } } } }, "400": { "description": "Invalid patch state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/healing/patches/:id/rollback": { "post": { "tags": [ "Healing" ], "summary": "Rollback patch", "description": "Rollback a previously applied patch, restoring the original pipeline configuration.", "operationId": "rollback_patch", "parameters": [ { "name": "id", "in": "path", "description": "Patch ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Patch rolled back", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyPatchResponse" } } } }, "400": { "description": "Invalid patch state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/health/services": { "get": { "tags": [ "Health" ], "summary": "Service registry health", "description": "Return health details for all registered internal services and connectors.", "operationId": "service_health", "responses": { "200": { "description": "Registered service health map" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/incidents": { "get": { "tags": [ "Incidents" ], "summary": "List incidents", "operationId": "list_incidents", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Incident list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Incidents" ], "summary": "Create incident", "operationId": "create_incident", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIncidentRequest" } } }, "required": true }, "responses": { "201": { "description": "Incident created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/incidents/{id}": { "get": { "tags": [ "Incidents" ], "summary": "Get incident", "operationId": "get_incident", "parameters": [ { "name": "id", "in": "path", "description": "Incident ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Incident details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Incidents" ], "summary": "Update incident", "operationId": "update_incident", "parameters": [ { "name": "id", "in": "path", "description": "Incident ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateIncidentRequest" } } }, "required": true }, "responses": { "200": { "description": "Incident updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/incidents/{id}/resolve": { "post": { "tags": [ "Incidents" ], "summary": "Resolve incident", "operationId": "resolve_incident", "parameters": [ { "name": "id", "in": "path", "description": "Incident ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveRequest" } } }, "required": true }, "responses": { "200": { "description": "Incident resolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/incidents/{id}/timeline": { "get": { "tags": [ "Incidents" ], "summary": "Get incident timeline", "operationId": "get_timeline", "parameters": [ { "name": "id", "in": "path", "description": "Incident ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Incident timeline", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IncidentEventResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/incidents/{id}/triage": { "post": { "tags": [ "Incidents" ], "summary": "Triage incident", "operationId": "triage_incident", "parameters": [ { "name": "id", "in": "path", "description": "Incident ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriageRequest" } } }, "required": true }, "responses": { "200": { "description": "Incident triaged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IncidentResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/indexnow/key/generate": { "post": { "tags": [ "IndexNow" ], "summary": "Generate IndexNow key", "description": "Generate a new 32-character hex key for IndexNow authentication. The key is stored in the database. You must host the key as a text file at `https://{your-domain}/{key}.txt` for verification.", "operationId": "generate_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "Key generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateKeyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/indexnow/key/verify": { "get": { "tags": [ "IndexNow" ], "summary": "Verify IndexNow key", "description": "Check whether the stored IndexNow key file is accessible on the site.", "operationId": "verify_key", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Key verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyKeyResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No key stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/indexnow/submit": { "post": { "tags": [ "IndexNow" ], "summary": "Submit URLs via IndexNow", "description": "Submit URLs to all IndexNow-participating search engines (Bing, Yandex, Naver, Seznam). Uses stored key from DB if not provided in request.", "operationId": "submit", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexNowSubmitRequest" } } }, "required": true }, "responses": { "200": { "description": "URLs submitted via IndexNow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndexNowSubmitResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/inspection/html": { "post": { "tags": [ "Inspection" ], "summary": "Analyze HTML", "description": "Analyze provided HTML content for headings, meta tags, links, images, and issues.", "operationId": "analyze_html", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeHtmlRequest" } } }, "required": true }, "responses": { "200": { "description": "HTML analysis result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyzeHtmlResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/inspection/selectors": { "post": { "tags": [ "Inspection" ], "summary": "Find selectors", "description": "Find CSS selectors that match target text on a page.", "operationId": "find_selectors", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindSelectorsRequest" } } }, "required": true }, "responses": { "200": { "description": "Discovered selectors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindSelectorsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/inspection/url": { "post": { "tags": [ "Inspection" ], "summary": "Inspect URL", "description": "Fetch a URL and return metadata, links, images, structured data, and response headers.", "operationId": "inspect_url", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "URL inspection result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectUrlResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/causal": { "post": { "tags": [ "Intelligence" ], "summary": "Estimate causal effect of SEO intervention", "operationId": "causal_effect", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CausalEffectRequest" } } }, "required": true }, "responses": { "200": { "description": "Causal effect estimation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CausalEffectResponse" } } } }, "503": { "description": "SBP sidecar unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/enrich": { "post": { "tags": [ "Intelligence" ], "summary": "Enrich domain with firmographics", "operationId": "enrich", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichRequest" } } }, "required": true }, "responses": { "200": { "description": "Enriched domain data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } }, "503": { "description": "SBP sidecar unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/forecast": { "post": { "tags": [ "Intelligence" ], "summary": "Revenue forecast with SEO assumptions", "operationId": "forecast", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastRequest" } } }, "required": true }, "responses": { "200": { "description": "Revenue forecast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastResponse" } } } }, "503": { "description": "SBP sidecar unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/graph": { "get": { "tags": [ "Intelligence" ], "summary": "Query knowledge graph", "operationId": "query_graph", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "site_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } } ], "responses": { "200": { "description": "Knowledge graph results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnowledgeGraphResponse" } } } }, "503": { "description": "SBP sidecar unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/graph/impact": { "post": { "tags": [ "Intelligence" ], "summary": "Analyze downstream impact of a node", "operationId": "graph_impact", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphImpactRequest" } } }, "required": true }, "responses": { "200": { "description": "Impact analysis results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphImpactResponse" } } } }, "404": { "description": "Node not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/graph/propagate": { "post": { "tags": [ "Intelligence" ], "summary": "Simulate signal propagation through graph", "operationId": "graph_propagate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphPropagateRequest" } } }, "required": true }, "responses": { "200": { "description": "Propagation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphPropagateResponse" } } } }, "400": { "description": "Invalid signal type" }, "404": { "description": "Source node not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/graph/root-cause": { "post": { "tags": [ "Intelligence" ], "summary": "Trace root causes of an anomaly", "operationId": "graph_root_cause", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRootCauseRequest" } } }, "required": true }, "responses": { "200": { "description": "Root cause analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphRootCauseResponse" } } } }, "404": { "description": "Node not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/insights": { "get": { "tags": [ "Intelligence" ], "summary": "AI-generated strategic insights", "operationId": "insights", "responses": { "200": { "description": "Strategic insights", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsightsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/score": { "post": { "tags": [ "Intelligence" ], "summary": "Score lead against ICP", "operationId": "score_lead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreLeadRequest" } } }, "required": true }, "responses": { "200": { "description": "Lead score", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreLeadResponse" } } } }, "503": { "description": "SBP sidecar unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/intelligence/simulate": { "post": { "tags": [ "Intelligence" ], "summary": "Run Monte Carlo simulation", "operationId": "simulate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationRequest" } } }, "required": true }, "responses": { "200": { "description": "Simulation results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResponse" } } } }, "503": { "description": "SBP sidecar unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/keywords": { "get": { "tags": [ "Keywords" ], "operationId": "list", "parameters": [ { "name": "site_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "priority", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List keywords", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordDto" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Keywords" ], "operationId": "batch_update", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch update keywords", "content": { "application/json": { "schema": {} } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/keywords/enrich": { "post": { "tags": [ "Keywords" ], "summary": "Enrich keywords with volume/difficulty", "description": "Internal endpoint for workflow-driven keyword enrichment via SeoDataProvider. Authenticated via service key.", "operationId": "enrich", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichRequest" } } }, "required": true }, "responses": { "200": { "description": "Enriched keywords", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/keywords/import/csv": { "post": { "tags": [ "Keywords" ], "operationId": "import_csv", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportCsvRequest" } } }, "required": true }, "responses": { "200": { "description": "Import keywords from CSV", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/keywords/import/gsc": { "post": { "tags": [ "Keywords" ], "operationId": "import_gsc", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportGscRequest" } } }, "required": true }, "responses": { "200": { "description": "Import keywords from GSC", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/keywords/recommend": { "post": { "tags": [ "Keywords" ], "operationId": "recommend", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendRequest" } } }, "required": true }, "responses": { "200": { "description": "Get keyword recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecommendResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/landscape": { "get": { "tags": [ "Landscape" ], "operationId": "get_landscape", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get competitive landscape", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LandscapeResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - insufficient tier" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/landscape/competitors": { "put": { "tags": [ "Landscape" ], "operationId": "update_competitors", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCompetitorsRequest" } } }, "required": true }, "responses": { "200": { "description": "Update competitors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitorsUpdatedResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - insufficient tier" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/leads": { "get": { "tags": [ "Leads" ], "summary": "List leads", "operationId": "list_leads", "parameters": [ { "name": "tier", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of leads", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LeadResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Leads" ], "summary": "Create a lead", "operationId": "create_lead", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLeadRequest" } } }, "required": true }, "responses": { "201": { "description": "Lead created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/leads/:id": { "get": { "tags": [ "Leads" ], "summary": "Get a lead", "operationId": "get_lead", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lead details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Leads" ], "summary": "Delete a lead", "operationId": "delete_lead", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lead deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/leads/:id/score": { "put": { "tags": [ "Leads" ], "summary": "Re-score a lead", "operationId": "rescore_lead", "parameters": [ { "name": "id", "in": "path", "description": "Lead ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Lead re-scored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/leads/signals": { "get": { "tags": [ "Leads" ], "summary": "List lead signals", "operationId": "list_signals", "parameters": [ { "name": "lead_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "signal_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "source", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of signals", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SignalResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Leads" ], "summary": "Record a lead signal", "operationId": "record_signal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordSignalRequest" } } }, "required": true }, "responses": { "201": { "description": "Signal recorded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignalResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/lineage/assets": { "get": { "tags": [ "Lineage" ], "operationId": "list_assets", "parameters": [ { "name": "asset_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List data assets", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Lineage" ], "operationId": "create_asset", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetRequest" } } }, "required": true }, "responses": { "200": { "description": "Asset created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/lineage/assets/{asset_id}": { "get": { "tags": [ "Lineage" ], "operationId": "get_asset", "parameters": [ { "name": "asset_id", "in": "path", "description": "Asset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get asset detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/lineage/assets/{asset_id}/graph": { "get": { "tags": [ "Lineage" ], "operationId": "get_graph", "parameters": [ { "name": "asset_id", "in": "path", "description": "Asset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get lineage DAG", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GraphResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/lineage/consent": { "get": { "tags": [ "Lineage" ], "operationId": "list_consent", "parameters": [ { "name": "domain", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "consent_status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List consent records", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ConsentResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Lineage" ], "operationId": "create_consent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConsentRequest" } } }, "required": true }, "responses": { "200": { "description": "Consent record created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/lineage/edges": { "post": { "tags": [ "Lineage" ], "operationId": "create_edge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEdgeRequest" } } }, "required": true }, "responses": { "200": { "description": "Lineage edge created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EdgeResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/links": { "post": { "tags": [ "Content" ], "operationId": "links", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksRequest" } } }, "required": true }, "responses": { "200": { "description": "Suggest internal links", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinksResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - insufficient tier" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/attributions": { "get": { "tags": [ "Measurement" ], "operationId": "list_attributions", "parameters": [ { "name": "model_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List attributions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MeasurementAttributionResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/calibrate": { "post": { "tags": [ "Measurement" ], "operationId": "calibrate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalibrateRequest" } } }, "required": true }, "responses": { "200": { "description": "Calibration triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalibrateResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/calibration-history": { "get": { "tags": [ "Measurement" ], "operationId": "calibration_history", "responses": { "200": { "description": "Calibration history", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CalibrationHistoryEntry" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/dashboard": { "get": { "tags": [ "Measurement" ], "operationId": "dashboard", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Dashboard statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeasurementDashboardResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/experiments": { "get": { "tags": [ "Measurement" ], "operationId": "list_experiments", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List experiments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Measurement" ], "operationId": "create_experiment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExperimentRequest" } } }, "required": true }, "responses": { "200": { "description": "Experiment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/experiments/{id}": { "get": { "tags": [ "Measurement" ], "operationId": "get_experiment", "parameters": [ { "name": "id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get experiment by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/experiments/{id}/cancel": { "post": { "tags": [ "Measurement" ], "operationId": "cancel_experiment", "parameters": [ { "name": "id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Experiment cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/measurement/observations/{exp_id}": { "get": { "tags": [ "Measurement" ], "operationId": "list_observations", "parameters": [ { "name": "exp_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List observations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ObservationResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/observatory/anomalies": { "get": { "tags": [ "Observatory" ], "operationId": "list_anomalies", "parameters": [ { "name": "dataset_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "severity", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List anomalies", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AnomalyResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/observatory/compare": { "post": { "tags": [ "Observatory" ], "operationId": "compare_profiles", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile comparison", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/observatory/profile": { "post": { "tags": [ "Observatory" ], "operationId": "create_profile", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/observatory/profiles/{dataset_id}": { "get": { "tags": [ "Observatory" ], "operationId": "get_profiles", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "List profiles for dataset", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProfileResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/billing-codes": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Upsert billing codes", "description": "Batch upsert CPT, HCPCS, MS-DRG, or other billing-code reference rows.", "operationId": "upsert_billing_codes", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertRequest_BillingCodeItem" } } }, "required": true }, "responses": { "200": { "description": "Billing codes upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/geo": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Upsert geographic references", "description": "Batch upsert ZIP, county, CBSA, and Medicare locality reference rows.", "operationId": "upsert_geo", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertRequest_GeoRefItem" } } }, "required": true }, "responses": { "200": { "description": "Geographic reference rows upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/hospitals": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Upsert hospitals", "description": "Batch upsert hospital identity, NPI, CMS certification, ownership, and location rows.", "operationId": "upsert_hospitals", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertRequest_HospitalItem" } } }, "required": true }, "responses": { "200": { "description": "Hospitals upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/payers": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Upsert payers", "description": "Batch upsert payer and insurer reference rows.", "operationId": "upsert_payers", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertRequest_PayerItem" } } }, "required": true }, "responses": { "200": { "description": "Payers upserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines": { "get": { "tags": [ "OpenRate Admin" ], "summary": "List OpenRate runs", "description": "List OpenRate ingestion, discovery, reference-data, and refresh pipeline runs.", "operationId": "list_pipeline_runs", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "pipeline_name", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } } ], "responses": { "200": { "description": "OpenRate pipeline runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPipelineRunsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/:run_id": { "get": { "tags": [ "OpenRate Admin" ], "summary": "Get OpenRate run", "description": "Get detailed status, counters, errors, and configuration for an OpenRate ingestion pipeline run.", "operationId": "get_pipeline_run", "parameters": [ { "name": "run_id", "in": "path", "description": "OpenRate pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OpenRate pipeline run detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunDetail" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/bootstrap": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Trigger OpenRate bootstrap", "description": "Start the regional bootstrap pipeline for OpenRate reference data and initial rate ingestion.", "operationId": "trigger_bootstrap", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerBootstrapRequest" } } }, "required": true }, "responses": { "200": { "description": "Bootstrap pipeline run triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/cms-discovery": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Trigger CMS source discovery", "description": "Refresh CMS-discovered source catalogs used by OpenRate ingestion jobs.", "operationId": "trigger_cms_discovery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerCmsDiscoveryRequest" } } }, "required": true }, "responses": { "200": { "description": "CMS discovery triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/discover": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Trigger source discovery", "description": "Discover candidate hospital or payer transparency sources from seed URLs.", "operationId": "trigger_discovery", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerDiscoveryRequest" } } }, "required": true }, "responses": { "200": { "description": "Source discovery pipeline triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/hospital-mrf": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Trigger hospital MRF ingestion", "description": "Trigger ingestion for a hospital machine-readable file and normalize rates into OpenRate tables.", "operationId": "trigger_hospital_mrf", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerHospitalMrfRequest" } } }, "required": true }, "responses": { "200": { "description": "Hospital MRF ingestion triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/reference-data": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Trigger reference data import", "description": "Import reference datasets such as NPPES, Medicare fee schedules, geographies, and billing-code catalogs.", "operationId": "trigger_reference_data", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerReferenceDataRequest" } } }, "required": true }, "responses": { "200": { "description": "Reference data import triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/pipelines/tic-ingestion": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Trigger payer TiC ingestion", "description": "Trigger ingestion for payer transparency-in-coverage indexes and negotiated-rate files.", "operationId": "trigger_tic_ingestion", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerTicIngestionRequest" } } }, "required": true }, "responses": { "200": { "description": "Transparency-in-coverage ingestion triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TriggerPipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/schedules/start": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Start OpenRate schedule", "description": "Start a recurring OpenRate ingestion, refresh, or discovery schedule.", "operationId": "start_schedule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleStartRequest" } } }, "required": true }, "responses": { "200": { "description": "OpenRate schedule started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleActionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/schedules/stop": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Stop OpenRate schedule", "description": "Stop a recurring OpenRate ingestion, refresh, or discovery schedule.", "operationId": "stop_schedule", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleStopRequest" } } }, "required": true }, "responses": { "200": { "description": "OpenRate schedule stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleActionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/sources": { "get": { "tags": [ "OpenRate Admin" ], "summary": "List OpenRate sources", "description": "List OpenRate data sources such as hospital MRF URLs, payer TiC indexes, CMS catalogs, and reference imports.", "operationId": "list_data_sources", "parameters": [ { "name": "source_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "OpenRate source registry entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListDataSourcesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "OpenRate Admin" ], "summary": "Create OpenRate source", "description": "Register a healthcare pricing source for later discovery, ingestion, and freshness monitoring.", "operationId": "create_data_source", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDataSourceRequest" } } }, "required": true }, "responses": { "200": { "description": "OpenRate source registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataSourceDetail" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/stats": { "get": { "tags": [ "OpenRate Admin" ], "summary": "OpenRate stats", "description": "Get table counts, data freshness, and latest pipeline-run status for OpenRate.", "operationId": "get_stats", "responses": { "200": { "description": "OpenRate data and pipeline statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminStatsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/admin/views/refresh": { "post": { "tags": [ "OpenRate Admin" ], "summary": "Refresh OpenRate views", "description": "Refresh OpenRate materialized and query views used by search, comparison, and discrepancy endpoints.", "operationId": "refresh_views", "responses": { "200": { "description": "Materialized/query views refreshed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshViewsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/rates/compare": { "get": { "tags": [ "OpenRate" ], "summary": "Compare healthcare rates", "description": "Compare hospital, payer, cash, negotiated, and benchmark rates for a billing code across markets.", "operationId": "compare_rates", "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "code_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "cbsa", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "payer", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } } ], "responses": { "200": { "description": "Market comparison rows for a billing code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareRatesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/rates/discrepancies": { "get": { "tags": [ "OpenRate" ], "summary": "Find pricing discrepancies", "description": "Find outliers and discrepancies between hospital-published rates and payer transparency-in-coverage rates.", "operationId": "get_discrepancies", "parameters": [ { "name": "code", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "hospital_npi", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "payer", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "min_difference_pct", "in": "query", "required": false, "schema": { "type": [ "number", "null" ], "format": "double" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } } ], "responses": { "200": { "description": "Hospital-versus-insurer pricing discrepancy rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscrepanciesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/rates/pipeline-status": { "get": { "tags": [ "OpenRate" ], "summary": "OpenRate pipeline status", "description": "Get recent OpenRate pipeline runs and source counts across hospitals, providers, billing codes, payers, and rates.", "operationId": "get_pipeline_status", "responses": { "200": { "description": "OpenRate ingestion and normalization pipeline status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/openrate/rates/search": { "get": { "tags": [ "OpenRate" ], "summary": "Search healthcare rates", "description": "Search normalized healthcare price-transparency rates by procedure name, billing code, payer, state, ZIP code, or charge type.", "operationId": "search_rates", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "zip", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "payer", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "charge_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } } ], "responses": { "200": { "description": "Healthcare pricing rates matching a procedure, code, payer, or location", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRatesResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipeline": { "get": { "tags": [ "Pipeline" ], "summary": "Get pipeline overview", "operationId": "overview", "responses": { "200": { "description": "Pipeline overview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineOverview" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipeline/attribution": { "get": { "tags": [ "Pipeline" ], "summary": "Get SEO attribution data", "operationId": "attribution", "responses": { "200": { "description": "Attribution data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttributionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipeline/deals": { "get": { "tags": [ "Pipeline" ], "summary": "List deals", "operationId": "list_deals", "parameters": [ { "name": "stage", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of deals", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DealResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Pipeline" ], "summary": "Create a deal", "operationId": "create_deal", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDealRequest" } } }, "required": true }, "responses": { "201": { "description": "Deal created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipeline/deals/:id": { "put": { "tags": [ "Pipeline" ], "summary": "Update a deal", "operationId": "update_deal", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDealRequest" } } }, "required": true }, "responses": { "200": { "description": "Deal updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipeline/forecast": { "get": { "tags": [ "Pipeline" ], "summary": "Get pipeline forecast", "operationId": "forecast", "responses": { "200": { "description": "Pipeline forecast", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForecastResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines": { "get": { "tags": [ "Pipelines" ], "summary": "List pipelines", "description": "List enrichment pipelines with optional status/search filters.", "operationId": "list_pipelines", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "pipeline_kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of pipelines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Pipelines" ], "summary": "Create pipeline", "description": "Create a new enrichment pipeline with step definitions.", "operationId": "create_pipeline", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePipelineRequest" } } }, "required": true }, "responses": { "201": { "description": "Pipeline created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/:pipeline_id": { "get": { "tags": [ "Pipelines" ], "summary": "Get pipeline", "description": "Get an enrichment pipeline by ID.", "operationId": "get_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Pipeline details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Pipelines" ], "summary": "Update pipeline", "description": "Update an existing enrichment pipeline.", "operationId": "update_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePipelineRequest" } } }, "required": true }, "responses": { "200": { "description": "Pipeline updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Pipelines" ], "summary": "Delete pipeline", "description": "Delete an enrichment pipeline.", "operationId": "delete_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Pipeline deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/:pipeline_id/run": { "post": { "tags": [ "Pipelines" ], "summary": "Run pipeline", "description": "Start a new run of an enrichment pipeline.", "operationId": "run_pipeline", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunPipelineRequest" } } }, "required": true }, "responses": { "202": { "description": "Pipeline run started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/:pipeline_id/runs": { "get": { "tags": [ "Pipelines" ], "summary": "List runs", "description": "List runs of an enrichment pipeline.", "operationId": "list_runs", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of runs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/:pipeline_id/schedule": { "get": { "tags": [ "Pipelines" ], "summary": "Schedule status", "description": "Get the schedule status and next run time of a pipeline.", "operationId": "get_schedule_status", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/:pipeline_id/schedule/start": { "post": { "tags": [ "Pipelines" ], "summary": "Start schedule", "description": "Start a cron-based schedule for a pipeline.", "operationId": "start_schedule", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartScheduleRequest" } } }, "required": true }, "responses": { "200": { "description": "Schedule started", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleStatusResponse" } } } }, "400": { "description": "Invalid cron expression", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/:pipeline_id/schedule/stop": { "post": { "tags": [ "Pipelines" ], "summary": "Stop schedule", "description": "Stop a cron-based schedule for a pipeline.", "operationId": "stop_schedule", "parameters": [ { "name": "pipeline_id", "in": "path", "description": "Pipeline ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Schedule stopped", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduleStatusResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/execute-step": { "post": { "tags": [ "Pipelines" ], "summary": "Execute pipeline step", "description": "Execute a single pipeline step. This endpoint is used by durable workflow workers and exposes the same Arrow-aware step handler registry used by full pipeline runs.", "operationId": "execute_step", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteStepRequest" } } }, "required": true }, "responses": { "200": { "description": "Step execution result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteStepResponse" } } } }, "400": { "description": "Step failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/runs/:run_id": { "get": { "tags": [ "Pipelines" ], "summary": "Get run", "description": "Get a pipeline run by ID.", "operationId": "get_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineRunResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/runs/:run_id/cancel": { "post": { "tags": [ "Pipelines" ], "summary": "Cancel run", "description": "Cancel a running or paused pipeline execution.", "operationId": "cancel_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineActionResponse" } } } }, "400": { "description": "Cannot cancel", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/runs/:run_id/lineage": { "put": { "tags": [ "Pipelines" ], "summary": "Emit run lineage", "description": "Register source, intermediate, output, and workflow-run assets plus lineage edges for a completed durable pipeline run.", "operationId": "emit_run_lineage", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitRunLineageRequest" } } }, "required": true }, "responses": { "200": { "description": "Lineage emitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmitRunLineageResponse" } } } }, "400": { "description": "Invalid lineage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/runs/:run_id/pause": { "post": { "tags": [ "Pipelines" ], "summary": "Pause run", "description": "Pause a running pipeline execution.", "operationId": "pause_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run paused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PipelineActionResponse" } } } }, "400": { "description": "Cannot pause", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/runs/:run_id/progress": { "put": { "tags": [ "Pipelines" ], "summary": "Update run progress", "description": "Update row, byte, and step-level progress for a running durable pipeline workflow.", "operationId": "update_run_progress", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRunProgressRequest" } } }, "required": true }, "responses": { "200": { "description": "Progress updated" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/pipelines/runs/:run_id/status": { "put": { "tags": [ "Pipelines" ], "summary": "Update run status", "description": "Update final or intermediate status for a durable pipeline run.", "operationId": "update_run_status", "parameters": [ { "name": "run_id", "in": "path", "description": "Pipeline run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRunStatusRequest" } } }, "required": true }, "responses": { "200": { "description": "Status updated" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Run not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/profile": { "get": { "tags": [ "Profile" ], "operationId": "get_profile", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get business profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Profile" ], "operationId": "update", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Update business profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/profile/generate": { "post": { "tags": [ "Profile" ], "operationId": "generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateProfileRequest" } } }, "required": true }, "responses": { "200": { "description": "Generate business profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/classify": { "post": { "tags": [ "Quality" ], "summary": "Classify text content using the taxonomy engine", "operationId": "classify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Classification results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassifyResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/decontaminate": { "post": { "tags": [ "Quality" ], "summary": "Check texts for benchmark contamination", "description": "Check whether provided texts contain overlap with common ML benchmarks (MMLU, HellaSwag, ARC, etc.). Returns per-text contamination details.", "operationId": "decontaminate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecontaminateRequest" } } }, "required": true }, "responses": { "200": { "description": "Decontamination results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecontaminateResponse" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/dedup": { "post": { "tags": [ "Quality" ], "operationId": "run_dedup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupRequest" } } }, "required": true }, "responses": { "200": { "description": "Deduplication results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DedupResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/filter": { "post": { "tags": [ "Quality" ], "operationId": "run_filter", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterRequest" } } }, "required": true }, "responses": { "200": { "description": "Heuristic filter results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/gate": { "post": { "tags": [ "Quality" ], "summary": "Run structured quality gate", "description": "Apply policy rules to dataset rows. Rules operate on raw JSON data (not text). Returns passed and quarantined rows with per-row violation details.", "operationId": "run_gate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateRequest" } } }, "required": true }, "responses": { "200": { "description": "Quality gate results with pass/quarantine split", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/profiles/{dataset_id}": { "get": { "tags": [ "Quality" ], "operationId": "get_profiles", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Quality profiles for dataset", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QualityProfileResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/score": { "post": { "tags": [ "Quality" ], "operationId": "compute_score", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Quality score for dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/quality/taxonomy": { "get": { "tags": [ "Quality" ], "summary": "Get the taxonomy tree", "operationId": "get_taxonomy", "responses": { "200": { "description": "Taxonomy tree", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaxonomyTreeResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query": { "post": { "tags": [ "Query" ], "summary": "Execute a SQL query over Parquet files", "operationId": "execute_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query results" }, "400": { "description": "Invalid SQL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/arrow": { "post": { "tags": [ "Query" ], "summary": "Arrow-native query", "description": "Execute SQL via DataFusion and return results as JSON.", "operationId": "arrow_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArrowQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridQueryResponse" } } } }, "400": { "description": "Invalid SQL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/describe": { "post": { "tags": [ "Query" ], "summary": "Describe schema of a Parquet file", "operationId": "describe_path", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DescribeRequest" } } }, "required": true }, "responses": { "200": { "description": "Column info" }, "400": { "description": "Invalid path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/export": { "post": { "tags": [ "Query" ], "summary": "Export query results", "description": "Execute SQL and write results to object store as Parquet, CSV, or JSON.", "operationId": "export_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Export complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/hybrid": { "post": { "tags": [ "Query" ], "summary": "Hybrid SQL query", "description": "Execute SQL over DuckDB views registered from Parquet files.", "operationId": "hybrid_query", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "Query results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HybridQueryResponse" } } } }, "400": { "description": "Invalid SQL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/register-table": { "post": { "tags": [ "Query" ], "summary": "Register DataFusion table", "description": "Register a Parquet file as a DataFusion table for Arrow-native SQL queries.", "operationId": "register_table", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTableRequest" } } }, "required": true }, "responses": { "200": { "description": "Table registered" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/register-view": { "post": { "tags": [ "Query" ], "summary": "Register Parquet view", "description": "Register a Parquet file or glob as a DuckDB view for SQL queries.", "operationId": "register_view", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterViewRequest" } } }, "required": true }, "responses": { "200": { "description": "View registered" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/schema": { "post": { "tags": [ "Query" ], "summary": "Get view schema", "description": "Get the Arrow schema for a registered DuckDB view.", "operationId": "get_view_schema", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaQueryRequest" } } }, "required": true }, "responses": { "200": { "description": "View schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaQueryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/stats": { "post": { "tags": [ "Query" ], "summary": "Get stats for a Parquet path", "operationId": "get_stats", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatsRequest" } } }, "required": true }, "responses": { "200": { "description": "Parquet stats" }, "400": { "description": "Invalid path", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/query/views": { "get": { "tags": [ "Query" ], "summary": "List views", "description": "List registered DuckDB views.", "operationId": "list_views", "responses": { "200": { "description": "List of views" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/queue/dequeue": { "post": { "tags": [ "Queue" ], "summary": "Dequeue items", "description": "Claim items from a queue for processing with a lock duration.", "operationId": "dequeue", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DequeueRequest" } } }, "required": true }, "responses": { "200": { "description": "Dequeued items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DequeueResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/queue/enqueue": { "post": { "tags": [ "Queue" ], "summary": "Enqueue item", "description": "Add a new item to a named queue with optional priority and delay.", "operationId": "enqueue", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnqueueRequest" } } }, "required": true }, "responses": { "201": { "description": "Item enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueItemResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/queue/items": { "get": { "tags": [ "Queue" ], "summary": "List queue items", "description": "List items in a named queue with optional status filter.", "operationId": "list_items", "parameters": [ { "name": "queue_name", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Queue items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/queue/purge": { "post": { "tags": [ "Queue" ], "summary": "Purge queue", "description": "Remove completed/failed items from a queue, optionally filtered by age.", "operationId": "purge", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeRequest" } } }, "required": true }, "responses": { "200": { "description": "Items purged", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueActionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/queue/retry": { "post": { "tags": [ "Queue" ], "summary": "Retry queue item", "description": "Retry a failed or dead-letter queue item with optional delay.", "operationId": "retry_item", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryRequest" } } }, "required": true }, "responses": { "200": { "description": "Item retried", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueActionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Item not found or not retryable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/queue/stats": { "get": { "tags": [ "Queue" ], "summary": "Queue stats", "description": "Get count statistics for a named queue.", "operationId": "queue_stats", "parameters": [ { "name": "queue_name", "in": "query", "description": "Queue name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Queue statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueueStatsResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/report": { "post": { "tags": [ "Analysis" ], "operationId": "generate_report", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRequest" } } }, "required": true }, "responses": { "200": { "description": "Generate report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scheduled-audits": { "get": { "tags": [ "ScheduledAudits" ], "operationId": "list", "parameters": [ { "name": "site_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List scheduled audits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAuditListResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - Pro tier required" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "ScheduledAudits" ], "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScheduledAuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Create or update scheduled audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAuditResponse" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scheduled-audits/{id}": { "get": { "tags": [ "ScheduledAudits" ], "operationId": "get_one", "parameters": [ { "name": "id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get scheduled audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAuditResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "ScheduledAudits" ], "operationId": "update", "parameters": [ { "name": "id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateScheduledAuditRequest" } } }, "required": true }, "responses": { "200": { "description": "Update scheduled audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledAuditResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "ScheduledAudits" ], "operationId": "delete_one", "parameters": [ { "name": "id", "in": "path", "description": "Schedule ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Delete scheduled audit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteScheduledAuditResponse" } } } }, "404": { "description": "Not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/schema": { "post": { "tags": [ "Content" ], "operationId": "schema", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaRequest" } } }, "required": true }, "responses": { "200": { "description": "Generate JSON-LD schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden - insufficient tier" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/schemas": { "get": { "tags": [ "SchemaRegistry" ], "operationId": "list_schemas", "parameters": [ { "name": "schema_name", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List schemas", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaVersionResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "SchemaRegistry" ], "operationId": "create_schema", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSchemaRequest" } } }, "required": true }, "responses": { "200": { "description": "Created schema version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaVersionResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/schemas/validate": { "post": { "tags": [ "SchemaRegistry" ], "operationId": "validate_data", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateSchemaRequest" } } }, "required": true }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/schemas/{name}/versions": { "get": { "tags": [ "SchemaRegistry" ], "operationId": "get_versions", "parameters": [ { "name": "name", "in": "path", "description": "Schema name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Schema versions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SchemaVersionResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/batch": { "post": { "tags": [ "Scoring" ], "operationId": "batch_compute", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Batch score results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchScoreResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/compare": { "post": { "tags": [ "Scoring" ], "operationId": "compare", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareRequest" } } }, "required": true }, "responses": { "200": { "description": "Score comparison", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/compute": { "post": { "tags": [ "Scoring" ], "operationId": "compute_score", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComputeScoreRequest" } } }, "required": true }, "responses": { "200": { "description": "Score computation triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/explain": { "post": { "tags": [ "Scoring" ], "operationId": "explain", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainRequest" } } }, "required": true }, "responses": { "200": { "description": "Score explanation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExplainResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/history": { "get": { "tags": [ "Scoring" ], "operationId": "get_history", "parameters": [ { "name": "model_type", "in": "query", "description": "Model type", "required": true, "schema": { "type": "string" } }, { "name": "target_id", "in": "query", "description": "Target ID", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Max results (default 10)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Score history", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/models": { "get": { "tags": [ "Scoring" ], "operationId": "list_models", "responses": { "200": { "description": "List model configs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ModelConfigResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/models/{model_type}": { "put": { "tags": [ "Scoring" ], "operationId": "update_model", "parameters": [ { "name": "model_type", "in": "path", "description": "Model type", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWeightsRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated model config", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelConfigResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/results": { "get": { "tags": [ "Scoring" ], "operationId": "list_results", "parameters": [ { "name": "model_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "target_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List scores", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/scoring/results/{id}": { "get": { "tags": [ "Scoring" ], "operationId": "get_result", "parameters": [ { "name": "id", "in": "path", "description": "Score ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get score by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/seo/reports": { "get": { "tags": [ "SEO Reports" ], "operationId": "list", "parameters": [ { "name": "site_url", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "month", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } } ], "responses": { "200": { "description": "List SEO reports", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoReportListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/seo/reports/{report_id}": { "get": { "tags": [ "SEO Reports" ], "operationId": "get_report", "parameters": [ { "name": "report_id", "in": "path", "description": "Report ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get SEO report details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoReportResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/sites": { "get": { "tags": [ "Sites" ], "operationId": "list", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List sites for account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Sites" ], "operationId": "update", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteRequest" } } }, "required": true }, "responses": { "200": { "description": "Site updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Sites" ], "operationId": "create", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteRequest" } } }, "required": true }, "responses": { "201": { "description": "Site created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/sites/:site_id": { "get": { "tags": [ "Sites" ], "operationId": "get_site", "parameters": [ { "name": "site_id", "in": "path", "description": "Site ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get site details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Sites" ], "operationId": "delete_site", "parameters": [ { "name": "site_id", "in": "path", "description": "Site ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Site deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSiteResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/:platform/channels/:channel_id/profile": { "get": { "tags": [ "Social - Channels" ], "summary": "Get a channel profile for any supported social platform", "operationId": "get_channel_profile", "parameters": [ { "name": "platform", "in": "path", "description": "Social platform (reddit, linkedin)", "required": true, "schema": { "type": "string" } }, { "name": "channel_id", "in": "path", "description": "Platform channel identifier (subreddit name, LinkedIn company slug)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Channel profile envelope: { platform, channel_id, profile }" }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unsupported platform", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/linkedin/mentions": { "get": { "tags": [ "Social - LinkedIn" ], "summary": "List LinkedIn mentions", "operationId": "list_mentions", "parameters": [ { "name": "monitor_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "min_score", "in": "query", "required": false, "schema": { "type": [ "number", "null" ], "format": "double" } }, { "name": "seniority", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "company", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "industry", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of mentions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MentionResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/linkedin/mentions/:mention_id": { "get": { "tags": [ "Social - LinkedIn" ], "summary": "Get a LinkedIn mention", "operationId": "get_mention", "parameters": [ { "name": "mention_id", "in": "path", "description": "Mention ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Mention details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/linkedin/monitors": { "get": { "tags": [ "Social - LinkedIn" ], "summary": "List LinkedIn monitors", "operationId": "list_monitors", "parameters": [ { "name": "enabled", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "monitor_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List of monitors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Social - LinkedIn" ], "summary": "Create a LinkedIn monitor", "operationId": "create_monitor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorRequest" } } }, "required": true }, "responses": { "201": { "description": "Monitor created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/linkedin/monitors/:monitor_id": { "get": { "tags": [ "Social - LinkedIn" ], "summary": "Get a LinkedIn monitor", "operationId": "get_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Monitor details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Social - LinkedIn" ], "summary": "Update a LinkedIn monitor", "operationId": "update_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Monitor updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Social - LinkedIn" ], "summary": "Delete a LinkedIn monitor", "operationId": "delete_monitor_handler", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Monitor deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/linkedin/monitors/:monitor_id/poll": { "post": { "tags": [ "Social - LinkedIn" ], "summary": "Poll a LinkedIn monitor", "operationId": "poll_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Poll results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/authors/:author/comments": { "get": { "tags": [ "Social - Reddit" ], "summary": "Fetch recent comments authored by a Reddit user", "operationId": "fetch_author_comments", "parameters": [ { "name": "author", "in": "path", "description": "Reddit author handle", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "from", "in": "query", "description": "Inclusive lower bound on created_utc, epoch seconds. Forwarded to\nArctic Shift's `after`; omitted preserves the windowless default.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound on created_utc, epoch seconds. Forwarded to\nArctic Shift's `before`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Comments authored by the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorCommentsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/authors/:author/posts": { "get": { "tags": [ "Social - Reddit" ], "summary": "Fetch recent posts authored by a Reddit user", "operationId": "fetch_author_posts", "parameters": [ { "name": "author", "in": "path", "description": "Reddit author handle", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "from", "in": "query", "description": "Inclusive lower bound on created_utc, epoch seconds. Forwarded to\nArctic Shift's `after`; omitted preserves the windowless default.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound on created_utc, epoch seconds. Forwarded to\nArctic Shift's `before`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Posts authored by the user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorPostsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/discover": { "post": { "tags": [ "Social - Reddit" ], "summary": "Discover relevant Reddit communities by keywords", "operationId": "discover_communities_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityDiscoveryRequest" } } }, "required": true }, "responses": { "200": { "description": "Discovered communities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommunityDiscoveryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/mentions": { "get": { "tags": [ "Social - Reddit" ], "summary": "List Reddit mentions", "operationId": "list_mentions", "parameters": [ { "name": "monitor_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "min_score", "in": "query", "required": false, "schema": { "type": [ "number", "null" ], "format": "double" } }, { "name": "subreddit", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "q", "in": "query", "description": "Free-text search term. Purely a LIVE-fallback trigger: when the\npersisted-mentions query returns empty and this (or `subreddit`) is\npresent, mentions are fetched live (mirroring `/posts`). It does NOT\nfilter the DB query, so the default request shape is unchanged.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "description": "Inclusive lower bound on content creation time, epoch seconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound on content creation time, epoch seconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "sort", "in": "query", "description": "Sort order by time: \"asc\" or \"desc\" (default \"desc\").", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of mentions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MentionResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/mentions/:mention_id": { "get": { "tags": [ "Social - Reddit" ], "summary": "Get a Reddit mention", "operationId": "get_mention", "parameters": [ { "name": "mention_id", "in": "path", "description": "Mention ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Mention details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/monitors": { "get": { "tags": [ "Social - Reddit" ], "summary": "List Reddit monitors", "operationId": "list_monitors", "parameters": [ { "name": "enabled", "in": "query", "required": false, "schema": { "type": [ "boolean", "null" ] } }, { "name": "monitor_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "List of monitors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonitorResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Social - Reddit" ], "summary": "Create a Reddit monitor", "operationId": "create_monitor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMonitorRequest" } } }, "required": true }, "responses": { "201": { "description": "Monitor created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/monitors/:monitor_id": { "get": { "tags": [ "Social - Reddit" ], "summary": "Get a Reddit monitor", "operationId": "get_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Monitor details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Social - Reddit" ], "summary": "Update a Reddit monitor", "operationId": "update_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMonitorRequest" } } }, "required": true }, "responses": { "200": { "description": "Monitor updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Social - Reddit" ], "summary": "Delete a Reddit monitor", "operationId": "delete_monitor_handler", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Monitor deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/monitors/:monitor_id/poll": { "post": { "tags": [ "Social - Reddit" ], "summary": "Poll a Reddit monitor", "operationId": "poll_monitor", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Poll results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PollResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/monitors/:monitor_id/sentiment": { "get": { "tags": [ "Social - Reddit" ], "summary": "Get sentiment aggregation for a monitor", "operationId": "get_sentiment_aggregation", "parameters": [ { "name": "monitor_id", "in": "path", "description": "Monitor ID", "required": true, "schema": { "type": "string" } }, { "name": "window", "in": "query", "description": "Time window (e.g. 7d, 30d)", "required": false, "schema": { "type": "string" } }, { "name": "granularity", "in": "query", "description": "Data granularity (e.g. daily, hourly)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sentiment aggregation data" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/posts": { "get": { "tags": [ "Social - Reddit" ], "summary": "Fetch recent posts from a subreddit", "operationId": "fetch_subreddit_posts", "parameters": [ { "name": "subreddit", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "from", "in": "query", "description": "Inclusive lower bound on created_utc, epoch seconds. Passed upstream\nto archive sources that support it; enforced server-side otherwise.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound on created_utc, epoch seconds.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "sort", "in": "query", "description": "Sort order by created_utc: \"asc\" or \"desc\" (default \"desc\").", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Subreddit posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubredditPostsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/posts/:post_id/comments": { "get": { "tags": [ "Social - Reddit" ], "summary": "Fetch comments for a Reddit thread", "operationId": "fetch_thread_comments", "parameters": [ { "name": "post_id", "in": "path", "description": "Reddit post (thread) id", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "from", "in": "query", "description": "Inclusive lower bound on created_utc, epoch seconds. Forwarded to\nArctic Shift's `after`; omitted preserves the windowless default.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "to", "in": "query", "description": "Inclusive upper bound on created_utc, epoch seconds. Forwarded to\nArctic Shift's `before`.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Comments belonging to the thread", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ThreadCommentsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/posts/:post_id/metrics": { "get": { "tags": [ "Social - Reddit" ], "summary": "Fetch current metrics (score, comments, ratio) for a Reddit post by id", "operationId": "fetch_post_metrics", "parameters": [ { "name": "post_id", "in": "path", "description": "Reddit post (thread) id, with or without the t3_ prefix", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current engagement metrics for the post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedditPostMetrics" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No post found for the id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "Upstream metrics source unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/social/reddit/subreddits/:subreddit/profile": { "get": { "tags": [ "Social - Reddit" ], "summary": "Get subreddit profile", "operationId": "get_subreddit_profile_handler", "parameters": [ { "name": "subreddit", "in": "path", "description": "Subreddit name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subreddit profile data" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders": { "get": { "tags": [ "Spiders" ], "summary": "List spiders", "description": "List spider definitions with optional kind/status/search filters.", "operationId": "list_spiders", "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List of spiders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderListResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Spiders" ], "summary": "Create spider", "description": "Create a new spider definition for structured data extraction.", "operationId": "create_spider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSpiderRequest" } } }, "required": true }, "responses": { "201": { "description": "Spider created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/:spider_id": { "get": { "tags": [ "Spiders" ], "summary": "Get spider", "description": "Get a spider definition by ID.", "operationId": "get_spider", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spider details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Spiders" ], "summary": "Update spider", "description": "Update an existing spider definition.", "operationId": "update_spider", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSpiderRequest" } } }, "required": true }, "responses": { "200": { "description": "Spider updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Spiders" ], "summary": "Archive spider", "description": "Archive (soft-delete) a spider definition.", "operationId": "archive_spider", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Spider archived" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/:spider_id/export": { "post": { "tags": [ "Spiders" ], "summary": "Export spider", "description": "Export a spider definition as a portable JSON document.", "operationId": "export_spider", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spider exported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportSpiderResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/:spider_id/health": { "get": { "tags": [ "Spiders" ], "summary": "Spider health", "description": "Get the health status and field-level extraction completeness of a spider.", "operationId": "spider_health", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Spider health", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderHealthResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Spider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/:spider_id/repair": { "post": { "tags": [ "Spiders" ], "summary": "Repair spider selectors", "description": "Repair broken selectors or extraction rules using validation failures and AI-assisted selector alternatives.", "operationId": "repair_spider", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairSpiderRequest" } } }, "required": true }, "responses": { "200": { "description": "Repaired spider definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepairSpiderResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Spider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/:spider_id/test": { "post": { "tags": [ "Spiders" ], "summary": "Test spider", "description": "Test a spider definition against a URL to preview extraction results.", "operationId": "test_spider", "parameters": [ { "name": "spider_id", "in": "path", "description": "Spider definition ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSpiderRequest" } } }, "required": true }, "responses": { "200": { "description": "Test results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestSpiderResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Spider not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/build": { "post": { "tags": [ "Spiders" ], "summary": "Build spider with AI", "description": "Generate, validate, and optionally repair a declarative spider from representative URLs, desired fields, schema hints, and steering instructions.", "operationId": "build_spider_ai", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiBuildRequest" } } }, "required": true }, "responses": { "200": { "description": "AI-generated spider with validation diagnostics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiBuildResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/factory": { "post": { "tags": [ "Spiders" ], "summary": "Spider factory", "description": "Batch-create spiders for multiple URLs. Spawns parallel SpiderBuildWorkflows via Restate.", "operationId": "spider_factory", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderFactoryRequest" } } }, "required": true }, "responses": { "202": { "description": "Factory batch accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderFactoryResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/import": { "post": { "tags": [ "Spiders" ], "summary": "Import spider", "description": "Import a spider definition from a JSON export.", "operationId": "import_spider", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportSpiderRequest" } } }, "required": true }, "responses": { "201": { "description": "Spider imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpiderResponse" } } } }, "400": { "description": "Invalid definition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/spiders/suggest-fields": { "post": { "tags": [ "Spiders" ], "summary": "Suggest spider fields", "description": "Analyze a URL and suggest extractable fields, selectors, and field metadata for spider creation.", "operationId": "suggest_fields", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestFieldsRequest" } } }, "required": true }, "responses": { "200": { "description": "Suggested extractable fields and selectors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestFieldsResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/status": { "get": { "tags": [ "Analysis" ], "operationId": "status", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get site status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteStatusResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Site not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/synthetic/generate": { "post": { "tags": [ "Synthetic" ], "operationId": "generate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateRequest" } } }, "required": true }, "responses": { "200": { "description": "Synthetic data generation triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticJobResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/synthetic/guardrails/{dataset_id}": { "get": { "tags": [ "Synthetic" ], "operationId": "check_guardrails", "parameters": [ { "name": "dataset_id", "in": "path", "description": "Dataset ID to check guardrails for", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Guardrail check result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuardrailResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/synthetic/jobs": { "get": { "tags": [ "Synthetic" ], "operationId": "list_jobs", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "operation", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List synthetic jobs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SyntheticJobResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/synthetic/jobs/{id}": { "get": { "tags": [ "Synthetic" ], "operationId": "get_job", "parameters": [ { "name": "id", "in": "path", "description": "Synthetic job ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get synthetic job by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyntheticJobResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/synthetic/operations": { "get": { "tags": [ "Synthetic" ], "operationId": "list_operations", "responses": { "200": { "description": "List available operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/synthetic/verify": { "post": { "tags": [ "Synthetic" ], "operationId": "verify", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/dashboard": { "get": { "tags": [ "Telemetry" ], "operationId": "get_dashboard", "parameters": [ { "name": "project_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Telemetry dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelemetryDashboardResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/destinations": { "get": { "tags": [ "Telemetry" ], "operationId": "list_destinations", "responses": { "200": { "description": "List destinations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DestinationResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Telemetry" ], "operationId": "add_destination", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDestinationRequest" } } }, "required": true }, "responses": { "200": { "description": "Destination created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/destinations/{id}": { "put": { "tags": [ "Telemetry" ], "operationId": "update_destination", "parameters": [ { "name": "id", "in": "path", "description": "Destination ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDestinationRequest" } } }, "required": true }, "responses": { "200": { "description": "Destination updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DestinationResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Telemetry" ], "operationId": "delete_destination", "parameters": [ { "name": "id", "in": "path", "description": "Destination ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Destination deleted", "content": { "text/plain": { "schema": { "type": "boolean" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/errors": { "get": { "tags": [ "Telemetry" ], "operationId": "get_errors", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "service_name", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Aggregated errors", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorAggResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/events": { "get": { "tags": [ "Telemetry" ], "operationId": "query_events", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "event_type", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "session_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EventResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/funnel": { "post": { "tags": [ "Telemetry" ], "operationId": "get_funnel", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelRequest" } } }, "required": true }, "responses": { "200": { "description": "Funnel analysis", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FunnelResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/identify": { "post": { "tags": [ "Telemetry" ], "operationId": "identify_visitor", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentifyRequest" } } }, "required": true }, "responses": { "200": { "description": "Visitor identified" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/ingest": { "post": { "tags": [ "Telemetry" ], "operationId": "ingest_events", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEventsRequest" } } }, "required": true }, "responses": { "202": { "description": "Events accepted for ingestion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestEventsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/metrics": { "get": { "tags": [ "Telemetry" ], "operationId": "get_metrics", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "metric_name", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Query metrics", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetricResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/otlp": { "post": { "tags": [ "Telemetry" ], "summary": "OTLP handler for receiving OpenTelemetry data from the collector.", "description": "Authenticates via Bearer token matching CRAWLKIT_INTERNAL_KEY.\nAccepts OTLP JSON payload, extracts spans and metrics, stores them.", "operationId": "otlp_handler", "requestBody": { "content": { "application/json": { "schema": {} } }, "required": true }, "responses": { "200": { "description": "OTLP data accepted" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/projects": { "get": { "tags": [ "Telemetry" ], "operationId": "list_projects", "responses": { "200": { "description": "List projects", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Telemetry" ], "operationId": "create_project", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/projects/{id}": { "get": { "tags": [ "Telemetry" ], "operationId": "get_project", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Get project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Telemetry" ], "operationId": "update_project", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } }, "required": true }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Telemetry" ], "operationId": "delete_project", "parameters": [ { "name": "id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Project deleted", "content": { "text/plain": { "schema": { "type": "boolean" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/session/end": { "post": { "tags": [ "Telemetry" ], "operationId": "session_end", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionEndRequest" } } }, "required": true }, "responses": { "200": { "description": "Session ended" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/session/start": { "post": { "tags": [ "Telemetry" ], "operationId": "session_start", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStartRequest" } } }, "required": true }, "responses": { "200": { "description": "Session started" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/sessions": { "get": { "tags": [ "Telemetry" ], "operationId": "list_sessions", "parameters": [ { "name": "project_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "visitor_id", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "List sessions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionResponse" } } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/sessions/{id}": { "get": { "tags": [ "Telemetry" ], "operationId": "get_session", "parameters": [ { "name": "id", "in": "path", "description": "Session ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get session by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/telemetry/traces/{trace_id}": { "get": { "tags": [ "Telemetry" ], "operationId": "get_trace", "parameters": [ { "name": "trace_id", "in": "path", "description": "Trace ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get trace spans", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/usage": { "get": { "tags": [ "Usage" ], "summary": "Get the calling account's API usage, bucketed by key, endpoint group and day", "operationId": "get_usage", "parameters": [ { "name": "from", "in": "query", "description": "Start day (inclusive, UTC, `YYYY-MM-DD`). Defaults to 30 days ago.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "to", "in": "query", "description": "End day (inclusive, UTC, `YYYY-MM-DD`). Defaults to today.", "required": false, "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "endpoint_group", "in": "query", "description": "Filter to a single endpoint group (e.g. `crawl`, `social`).", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Usage buckets for the calling account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/white-label": { "get": { "tags": [ "Clients" ], "operationId": "get_white_label", "responses": { "200": { "description": "White-label settings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteLabelResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Clients" ], "operationId": "update_white_label", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWhiteLabelRequest" } } }, "required": true }, "responses": { "200": { "description": "Settings updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhiteLabelResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates": { "get": { "tags": [ "Workflow Templates" ], "summary": "List workflow templates", "description": "Returns account-scoped and system templates.", "operationId": "list_templates", "parameters": [ { "name": "status", "in": "query", "description": "Filter by status (default: \"active\").", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of results.", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "description": "Offset for pagination.", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of workflow templates", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "Workflow Templates" ], "summary": "Create workflow template", "operationId": "create_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Template created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/:id": { "get": { "tags": [ "Workflow Templates" ], "summary": "Get template by ID", "operationId": "get_template", "parameters": [ { "name": "id", "in": "path", "description": "Template ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Workflow template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "put": { "tags": [ "Workflow Templates" ], "summary": "Update workflow template", "description": "Updates the template and bumps the version number.", "operationId": "update_template", "parameters": [ { "name": "id", "in": "path", "description": "Template ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Template updated (version bumped)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "delete": { "tags": [ "Workflow Templates" ], "summary": "Delete (archive) workflow template", "description": "Soft-deletes the template by setting status to 'archived'.", "operationId": "delete_template", "parameters": [ { "name": "id", "in": "path", "description": "Template ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Template archived", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/:id/run": { "post": { "tags": [ "Workflow Templates" ], "summary": "Run workflow template", "description": "Execute a template with the given parameters via GenericPipelineWorkflow.", "operationId": "run_template", "parameters": [ { "name": "id", "in": "path", "description": "Template ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Workflow run triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunTemplateResponse" } } } }, "400": { "description": "Bad request (parameter error)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/by-name/:name": { "get": { "tags": [ "Workflow Templates" ], "summary": "Get template by name", "description": "Returns the latest active version of the named template.", "operationId": "get_template_by_name", "parameters": [ { "name": "name", "in": "path", "description": "Template name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Workflow template (latest active version)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/operations": { "get": { "tags": [ "Workflow Templates" ], "summary": "List registered operations", "description": "Returns all step handler operations with capabilities and availability status.", "operationId": "list_operations", "responses": { "200": { "description": "List of registered operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationsListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/operations/:name": { "get": { "tags": [ "Workflow Templates" ], "summary": "Get operation details", "description": "Returns config schema, capabilities, and availability for a single operation.", "operationId": "get_operation", "parameters": [ { "name": "name", "in": "path", "description": "Operation name", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperationDetail" } } } }, "404": { "description": "Operation not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/runs": { "get": { "tags": [ "Workflow Templates" ], "summary": "List workflow runs", "operationId": "list_runs", "parameters": [ { "name": "template_id", "in": "query", "description": "Filter by template ID.", "required": false, "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "status", "in": "query", "description": "Filter by status.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "List of pipeline runs", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RunResponse" } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/runs/:run_id": { "get": { "tags": [ "Workflow Templates" ], "summary": "Get workflow run details", "operationId": "get_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResponse" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/runs/:run_id/cancel": { "post": { "tags": [ "Workflow Templates" ], "summary": "Cancel a running workflow", "description": "Cancels a pipeline run that is in 'running' or 'queued' status.", "operationId": "cancel_run", "parameters": [ { "name": "run_id", "in": "path", "description": "Run ID", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Run cancelled", "content": { "application/json": { "schema": {} } } }, "404": { "description": "Run not found or not cancellable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/workflow-templates/validate": { "post": { "tags": [ "Workflow Templates" ], "summary": "Validate workflow template", "description": "Checks operation existence, DAG acyclicity, dependency resolution, parameter completeness, and name uniqueness.", "operationId": "validate_template", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateTemplateRequest" } } }, "required": true }, "responses": { "200": { "description": "Validation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "description": "Returns service health status.", "operationId": "health", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/v1/search": { "post": { "tags": [ "Search" ], "summary": "Web/document search (honest provenance)", "operationId": "search", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } }, "required": true }, "responses": { "200": { "description": "Ranked search results with honest provenance label", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "description": "Invalid query or k", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Missing or invalid credentials", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AddClientRequest": { "type": "object", "required": [ "client_account_id" ], "properties": { "client_account_id": { "type": "string", "format": "uuid" } } }, "AddDomainRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" } } }, "AdminStatsResponse": { "type": "object", "required": [ "table_counts", "data_freshness" ], "properties": { "data_freshness": { "type": "array", "items": { "$ref": "#/components/schemas/DataSourceFreshness" } }, "latest_run": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PipelineRunDetail" } ] }, "table_counts": { "$ref": "#/components/schemas/TableCounts" } } }, "AdvanceCampaignRequest": { "type": "object", "required": [ "lead_ids" ], "properties": { "lead_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "AdvanceCampaignResponse": { "type": "object", "required": [ "advanced", "skipped" ], "properties": { "advanced": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } } }, "AffectedNodeDto": { "type": "object", "required": [ "node_id", "node_label", "node_type", "severity", "signal_type" ], "properties": { "node_id": { "type": "string", "format": "uuid" }, "node_label": { "type": "string" }, "node_type": { "type": "string" }, "severity": { "type": "number", "format": "double" }, "signal_type": { "type": "string" } } }, "AiBuildRequest": { "type": "object", "description": "Request to build a spider using AI.", "required": [ "target_url" ], "properties": { "description": { "type": [ "string", "null" ] }, "desired_fields": { "type": "array", "items": { "type": "string" } }, "include_debug_context": { "type": "boolean", "description": "Include richer prompt/context diagnostics in the returned metadata." }, "instructions": { "type": "array", "items": { "type": "string" }, "description": "Additional steering instructions. These are treated as high-priority prompt constraints." }, "max_context_chars": { "type": [ "integer", "null" ], "description": "Optional max DOM/context chars sent to the LLM.", "minimum": 0 }, "max_repair_attempts": { "type": "integer", "format": "int32", "description": "Maximum generate -> validate -> repair attempts after the initial build.", "minimum": 0 }, "min_success_rate": { "type": "number", "format": "double", "description": "Minimum validation success rate accepted before stopping repair attempts." }, "sample_urls": { "type": "array", "items": { "type": "string" }, "description": "Extra sample URLs with similar layout for validation/repair context." }, "target_schema": { "description": "Optional target output schema/example shape to guide fields and normalization." }, "target_url": { "type": "string" }, "test_after_build": { "type": "boolean", "description": "Whether to test the spider after generation (default: true)." } } }, "AiBuildResponse": { "type": "object", "description": "Response from AI spider build.", "required": [ "spider" ], "properties": { "diagnostics": { "description": "Builder-level diagnostics including repair attempts and AI metadata." }, "spider": { "$ref": "#/components/schemas/SpiderResponse" }, "validation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AiValidationResult" } ] } } }, "AiFieldFailure": { "type": "object", "description": "A field that failed validation.", "required": [ "field_name", "handler_name", "reason" ], "properties": { "field_name": { "type": "string" }, "handler_name": { "type": "string" }, "reason": { "type": "string" } } }, "AiGenerateRequest": { "type": "object", "description": "AI content generation request.", "required": [ "brief" ], "properties": { "brief": { "type": "string", "description": "Topic or brief for content generation" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "target_word_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "tone": { "type": [ "string", "null" ] } } }, "AiGenerateResponse": { "type": "object", "description": "AI generation response.", "required": [ "content_json", "title", "seo_score", "word_count" ], "properties": { "content_json": { "description": "Generated Plate.js document JSON" }, "seo_score": { "type": "integer", "format": "int32" }, "title": { "type": "string" }, "word_count": { "type": "integer", "format": "int32", "minimum": 0 } } }, "AiRewriteRequest": { "type": "object", "description": "AI rewrite request.", "required": [ "content_json", "instructions" ], "properties": { "content_json": { "description": "Content to rewrite (Plate.js block JSON)" }, "instructions": { "type": "string", "description": "Instructions for rewriting" }, "target_keywords": { "type": "array", "items": { "type": "string" } } } }, "AiRewriteResponse": { "type": "object", "description": "AI rewrite response.", "required": [ "content_json", "changes_summary" ], "properties": { "changes_summary": { "type": "string" }, "content_json": {} } }, "AiValidationResult": { "type": "object", "description": "Validation result from AI spider generation.", "required": [ "success_rate", "fields_extracted", "fields_total", "failures" ], "properties": { "diagnostics": {}, "failures": { "type": "array", "items": { "$ref": "#/components/schemas/AiFieldFailure" } }, "fields_extracted": { "type": "integer", "minimum": 0 }, "fields_total": { "type": "integer", "minimum": 0 }, "success_rate": { "type": "number", "format": "double" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "AlertDto": { "type": "object", "description": "Response DTO for a single alert notification.", "required": [ "id", "alert_type", "severity", "title", "description", "dismissed", "created_at" ], "properties": { "alert_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "dismissed": { "type": "boolean" }, "id": { "type": "integer", "format": "int64" }, "link": { "type": [ "string", "null" ] }, "related_pattern": { "type": [ "string", "null" ], "description": "Graphiti enrichment: temporal pattern context" }, "severity": { "type": "string" }, "site_domain": { "type": [ "string", "null" ] }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "temporal_context": { "type": [ "string", "null" ], "description": "Graphiti enrichment: historical context" }, "title": { "type": "string" } } }, "AlertInsightsResponse": { "type": "object", "description": "Graphiti-powered alert insights (Pro tier).", "required": [ "trending_issues", "recent_patterns" ], "properties": { "recent_patterns": { "type": "array", "items": { "$ref": "#/components/schemas/PatternSummary" } }, "trending_issues": { "type": "array", "items": { "$ref": "#/components/schemas/TrendingIssue" } } } }, "AlertListResponse": { "type": "object", "required": [ "alerts", "total", "unread_count" ], "properties": { "alerts": { "type": "array", "items": { "$ref": "#/components/schemas/AlertDto" } }, "total": { "type": "integer", "format": "int64" }, "unread_count": { "type": "integer", "format": "int64" } } }, "AnalyticsRequest": { "type": "object", "required": [ "site_id", "start_date", "end_date" ], "properties": { "dimensions": { "type": "array", "items": { "type": "string" } }, "end_date": { "type": "string" }, "row_limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "site_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string" } } }, "AnalyzeHtmlRequest": { "type": "object", "description": "Request to analyze HTML content.", "required": [ "html" ], "properties": { "base_url": { "type": [ "string", "null" ] }, "html": { "type": "string" } } }, "AnalyzeHtmlResponse": { "type": "object", "description": "Response for HTML analysis.", "required": [ "word_count", "heading_structure", "meta_tags", "links", "images", "structured_data", "issues" ], "properties": { "canonical": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "h1": { "type": [ "string", "null" ] }, "heading_structure": { "type": "array", "items": { "$ref": "#/components/schemas/HeadingDto" } }, "images": { "$ref": "#/components/schemas/ImageSummaryDto" }, "issues": { "type": "array", "items": { "type": "string" } }, "links": { "$ref": "#/components/schemas/LinkSummaryDto" }, "meta_tags": { "type": "array", "items": { "$ref": "#/components/schemas/MetaTagDto" } }, "structured_data": { "type": "array", "items": {} }, "title": { "type": [ "string", "null" ] }, "word_count": { "type": "integer", "minimum": 0 } } }, "AnomalyResponse": { "type": "object", "required": [ "id", "profile_id", "anomaly_type", "severity", "description", "detected_at" ], "properties": { "anomaly_type": { "type": "string" }, "description": { "type": "string" }, "detected_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "profile_id": { "type": "string", "format": "uuid" }, "severity": { "type": "string" } } }, "ApiTokenSummary": { "type": "object", "required": [ "id", "account_id", "name", "key_prefix", "created_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "key_prefix": { "type": "string" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "ApplyPatchResponse": { "type": "object", "description": "Response from applying or rolling back a patch.", "required": [ "success", "message" ], "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "ApprovalStatusResponse": { "type": "object", "description": "Approval status response.", "required": [ "id", "document_id", "status", "created_at", "updated_at" ], "properties": { "approver_id": { "type": [ "string", "null" ], "format": "uuid" }, "comments": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "document_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ArrowQueryRequest": { "type": "object", "description": "Request for an Arrow-native DataFusion query", "required": [ "sql" ], "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "sql": { "type": "string" } } }, "ArtifactDownloadResponse": { "type": "object", "required": [ "artifact_id", "status", "message" ], "properties": { "artifact_id": { "type": "string", "format": "uuid" }, "message": { "type": "string" }, "status": { "type": "string" } } }, "ArtifactResponse": { "type": "object", "required": [ "id", "account_id", "source_url", "status", "discovered_at", "metadata", "created_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "content_type": { "type": [ "string", "null" ] }, "crawl_job_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "discovered_at": { "type": "string", "format": "date-time" }, "discovery_context": { "type": [ "string", "null" ] }, "downloaded_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_message": { "type": [ "string", "null" ] }, "file_extension": { "type": [ "string", "null" ] }, "file_hash": { "type": [ "string", "null" ] }, "file_size_bytes": { "type": [ "integer", "null" ], "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "object_store_path": { "type": [ "string", "null" ] }, "parsed_at": { "type": [ "string", "null" ], "format": "date-time" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_url": { "type": "string" }, "spider_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" } } }, "ArtifactUrlResponse": { "type": "object", "required": [ "url", "expires_in_secs" ], "properties": { "expires_in_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "url": { "type": "string" } } }, "AssetDefinitionResponse": { "type": "object", "required": [ "id", "name", "asset_type", "source_config", "is_active", "created_at", "updated_at" ], "properties": { "asset_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "name": { "type": "string" }, "quality_gate": {}, "schedule_cron": { "type": [ "string", "null" ] }, "source_config": {}, "transform_pipeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "AssetResponse": { "type": "object", "required": [ "id", "name", "asset_type", "metadata", "created_at" ], "properties": { "asset_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "created_by_pipeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by_step_index": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "metadata": {}, "name": { "type": "string" }, "source_uri": { "type": [ "string", "null" ] } } }, "AttributionDto": { "type": "object", "required": [ "traffic_delta", "leads_attributed", "revenue_attributed_cents", "confidence", "method", "measured_at" ], "properties": { "confidence": { "type": "number", "format": "double" }, "fix_id": { "type": [ "string", "null" ], "format": "uuid" }, "leads_attributed": { "type": "integer", "format": "int32" }, "measured_at": { "type": "string", "format": "date-time" }, "method": { "type": "string" }, "revenue_attributed_cents": { "type": "integer", "format": "int64" }, "traffic_delta": { "type": "integer", "format": "int32" } } }, "AttributionResponse": { "type": "object", "required": [ "attributions" ], "properties": { "attributions": { "type": "array", "items": { "$ref": "#/components/schemas/AttributionDto" } } } }, "AuditDetailResponse": { "type": "object", "required": [ "audit" ], "properties": { "audit": { "$ref": "#/components/schemas/AuditDto" }, "results": {} } }, "AuditDto": { "type": "object", "required": [ "id", "site_id", "domain", "status", "critical_count", "high_count", "medium_count", "low_count", "created_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "critical_count": { "type": "integer", "format": "int64" }, "domain": { "type": "string" }, "duration_secs": { "type": [ "number", "null" ], "format": "double" }, "high_count": { "type": "integer", "format": "int64" }, "id": { "type": "string", "format": "uuid" }, "issues_found": { "type": [ "integer", "null" ], "format": "int32" }, "low_count": { "type": "integer", "format": "int64" }, "medium_count": { "type": "integer", "format": "int64" }, "pages_crawled": { "type": [ "integer", "null" ], "format": "int32" }, "score": { "type": [ "integer", "null" ], "format": "int32" }, "site_id": { "type": "string", "format": "uuid" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" } } }, "AuditListResponse": { "type": "object", "required": [ "audits", "total" ], "properties": { "audits": { "type": "array", "items": { "$ref": "#/components/schemas/AuditDto" } }, "total": { "type": "integer", "format": "int64" } } }, "AuditRequest": { "type": "object", "required": [ "url" ], "properties": { "identity": { "type": "object", "description": "Optional visitor identity for rate limiting" }, "url": { "type": "string", "description": "URL to audit (must be a valid HTTP/HTTPS URL)" } } }, "AuditScheduleFrequency": { "type": "string", "enum": [ "daily", "weekly" ] }, "AuthCallbackRequest": { "type": "object", "required": [ "code", "redirect_uri", "site_id" ], "properties": { "code": { "type": "string" }, "redirect_uri": { "type": "string" }, "site_id": { "type": "string", "format": "uuid" } } }, "AuthCallbackResponse": { "type": "object", "required": [ "connected" ], "properties": { "connected": { "type": "boolean" } } }, "AuthUrlRequest": { "type": "object", "required": [ "site_id" ], "properties": { "redirect_uri": { "type": [ "string", "null" ], "description": "Exact Google-authorized redirect URI. Defaults to the configured CrawlKit\nbrowser callback when omitted." }, "site_id": { "type": "string", "format": "uuid", "description": "Site that will receive the resulting Google Search Console connection." } } }, "AuthUrlResponse": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "AuthorCommentsResponse": { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" } } } }, "AuthorPostsResponse": { "type": "object", "required": [ "posts" ], "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/SubredditPost" } } } }, "AutoHealRequest": { "type": "object", "description": "Request to attempt autonomous auto-healing of a failed pipeline run.", "required": [ "pipeline_id", "failed_run_id", "error_context" ], "properties": { "error_context": {}, "failed_run_id": { "type": "string", "format": "uuid" }, "pipeline_id": { "type": "string", "format": "uuid" } } }, "AutoHealResult": { "type": "object", "description": "Result of an auto-heal attempt.", "required": [ "auto_healed", "reason" ], "properties": { "auto_healed": { "type": "boolean" }, "healed_run_id": { "type": [ "string", "null" ], "format": "uuid", "description": "ID of the new pipeline run triggered after healing (if auto-healed)." }, "patch_id": { "type": [ "string", "null" ], "format": "uuid" }, "reason": { "type": "string" } } }, "BatchError": { "type": "object", "required": [ "target_id", "error" ], "properties": { "error": { "type": "string" }, "target_id": { "type": "string" } } }, "BatchInspectRequest": { "type": "object", "required": [ "site_id", "urls" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "urls": { "type": "array", "items": { "type": "string" } } } }, "BatchScoreRequest": { "type": "object", "required": [ "model_type", "target_type", "target_ids" ], "properties": { "model_type": { "type": "string" }, "target_ids": { "type": "array", "items": { "type": "string" } }, "target_type": { "type": "string" } } }, "BatchScoreResponse": { "type": "object", "required": [ "results", "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/BatchError" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "BatchUpdateRequest": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordUpdate" } } } }, "BatchUpsertRequest_BillingCodeItem": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "code", "code_type" ], "properties": { "category": { "type": [ "string", "null" ] }, "code": { "type": "string" }, "code_type": { "type": "string" }, "consumer_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_shoppable": { "type": [ "boolean", "null" ] }, "setting": { "type": [ "string", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "subcategory": { "type": [ "string", "null" ] } } } } } }, "BatchUpsertRequest_GeoRefItem": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "zip" ], "properties": { "cbsa_code": { "type": [ "string", "null" ] }, "cbsa_name": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "medicare_locality": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": "string" } } } } } }, "BatchUpsertRequest_HospitalItem": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "hospital_name", "state" ], "properties": { "address_line1": { "type": [ "string", "null" ] }, "cbsa_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "cms_certification_number": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "emergency_services": { "type": [ "boolean", "null" ] }, "hospital_name": { "type": "string" }, "hospital_type": { "type": [ "string", "null" ] }, "npi": { "type": [ "string", "null" ] }, "ownership_type": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "zip": { "type": [ "string", "null" ] } } } } } }, "BatchUpsertRequest_PayerItem": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "canonical_name", "display_name" ], "properties": { "canonical_name": { "type": "string" }, "display_name": { "type": "string" }, "ein": { "type": [ "string", "null" ] }, "is_major": { "type": [ "boolean", "null" ] }, "parent_company": { "type": [ "string", "null" ] }, "payer_type": { "type": [ "string", "null" ] } } } } } }, "BatchUpsertResponse": { "type": "object", "required": [ "inserted", "updated" ], "properties": { "inserted": { "type": "integer", "format": "int64", "minimum": 0 }, "updated": { "type": "integer", "format": "int64", "minimum": 0 } } }, "BenchmarkId": { "oneOf": [ { "type": "string", "enum": [ "mmlu" ] }, { "type": "string", "enum": [ "hella_swag" ] }, { "type": "string", "enum": [ "arc" ] }, { "type": "string", "enum": [ "wino_grande" ] }, { "type": "string", "enum": [ "truthful_qa" ] }, { "type": "string", "enum": [ "gsm8k" ] }, { "type": "string", "enum": [ "human_eval" ] }, { "type": "string", "enum": [ "mbpp" ] }, { "type": "object", "required": [ "custom" ], "properties": { "custom": { "type": "string" } } } ], "description": "Well-known benchmark identifiers." }, "BenchmarkInfo": { "type": "object", "description": "Information about a benchmark that was checked.", "required": [ "id", "text_count" ], "properties": { "id": { "type": "string" }, "text_count": { "type": "integer", "minimum": 0 } } }, "BillingCodeItem": { "type": "object", "required": [ "code", "code_type" ], "properties": { "category": { "type": [ "string", "null" ] }, "code": { "type": "string" }, "code_type": { "type": "string" }, "consumer_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "is_shoppable": { "type": [ "boolean", "null" ] }, "setting": { "type": [ "string", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "subcategory": { "type": [ "string", "null" ] } } }, "BriefDetailResponse": { "type": "object", "required": [ "brief", "outline", "content_gaps", "internal_links" ], "properties": { "brief": { "$ref": "#/components/schemas/BriefDto" }, "content_gaps": { "type": "array", "items": { "type": "string" } }, "internal_links": {}, "outline": {} } }, "BriefDto": { "type": "object", "required": [ "id", "site_id", "domain", "target_keyword", "related_keywords", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "keyword_id": { "type": [ "string", "null" ], "format": "uuid" }, "related_keywords": { "type": "array", "items": { "type": "string" } }, "site_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "target_keyword": { "type": "string" }, "target_word_count": { "type": [ "integer", "null" ], "format": "int32" }, "title": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } } }, "BriefListResponse": { "type": "object", "required": [ "briefs", "total" ], "properties": { "briefs": { "type": "array", "items": { "$ref": "#/components/schemas/BriefDto" } }, "total": { "type": "integer", "format": "int64" } } }, "BriefRequest": { "type": "object", "required": [ "site_id", "keyword" ], "properties": { "keyword": { "type": "string" }, "site_id": { "type": "string", "format": "uuid" } } }, "BriefResponse": { "type": "object", "required": [ "keyword", "brief" ], "properties": { "brief": {}, "keyword": { "type": "string" } } }, "CalendarEntry": { "type": "object", "description": "Calendar entry.", "required": [ "id", "title", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "title": { "type": "string" } } }, "CalendarResponse": { "type": "object", "description": "Calendar response.", "required": [ "entries" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CalendarEntry" } } } }, "CalibrateRequest": { "type": "object", "required": [ "model_type" ], "properties": { "model_type": { "type": "string" } } }, "CalibrateResponse": { "type": "object", "required": [ "status", "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string" } } }, "CalibrationHistoryEntry": { "type": "object", "required": [ "id", "model_type", "old_weights", "new_weights", "experiment_count", "reasoning", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "experiment_count": { "type": "integer", "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "model_type": { "type": "string" }, "new_weights": {}, "old_weights": {}, "reasoning": { "type": "string" } } }, "CampaignResponse": { "type": "object", "required": [ "id", "name", "stages", "scoring_rules", "status", "leads_count", "created_at" ], "properties": { "conversion_rate": { "type": [ "number", "null" ], "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "leads_count": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "scoring_rules": {}, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignStageDto" } }, "status": { "type": "string" } } }, "CampaignStageDto": { "type": "object", "required": [ "name", "advance_threshold" ], "properties": { "advance_threshold": { "type": "number", "format": "double" }, "name": { "type": "string" }, "order": { "type": "integer", "format": "int32" }, "requires_review": { "type": "boolean" } } }, "CanonicalDto": { "type": "object", "required": [ "both_resolve", "same_destination" ], "properties": { "both_resolve": { "type": "boolean" }, "canonical_domain": { "type": [ "string", "null" ] }, "redirect_type": { "type": [ "string", "null" ] }, "same_destination": { "type": "boolean" } } }, "CausalChainDto": { "type": "object", "required": [ "chain", "confidence", "root_cause_type" ], "properties": { "chain": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "confidence": { "type": "number", "format": "double" }, "root_cause_type": { "type": "string" } } }, "CausalEffectRequest": { "type": "object", "description": "Request to estimate causal effect of an SEO intervention.", "required": [ "treatment", "outcome" ], "properties": { "method": { "type": "string", "description": "Method: \"backdoor\", \"frontdoor\", \"iv\"" }, "observation_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Historical observation count or data reference" }, "outcome": { "type": "string", "description": "The outcome metric (e.g., \"organic_traffic\")" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "treatment": { "type": "string", "description": "The intervention (e.g., \"fix_missing_titles\")" } } }, "CausalEffectResponse": { "type": "object", "required": [ "ate", "confidence_interval", "p_value", "method", "significant", "interpretation" ], "properties": { "ate": { "type": "number", "format": "double" }, "confidence_interval": { "$ref": "#/components/schemas/ConfidenceIntervalDto" }, "interpretation": { "type": "string" }, "method": { "type": "string" }, "p_value": { "type": "number", "format": "double" }, "significant": { "type": "boolean" } } }, "ChannelFilter": { "type": "object", "description": "One structured result filter, as sent by OpenRecipe's channel-discovery\nflow under `channel_filters` / `filters`. `field` is one of\nmembers|activity|affinity|moderation_risk|keyword|description|name|nsfw and\n`operator` one of gte|lte|eq|contains|not_contains.", "required": [ "field", "operator" ], "properties": { "field": { "type": "string" }, "operator": { "type": "string" }, "value": { "description": "Free-form comparand: numbers for members/affinity thresholds, strings\nfor keyword/name/description matching, booleans for nsfw." } } }, "CheckContentRequest": { "type": "object", "required": [ "html" ], "properties": { "filename": { "type": [ "string", "null" ], "description": "Filename hint (e.g., \"page.tsx\") for framework-specific analysis." }, "framework": { "type": [ "string", "null" ] }, "html": { "type": "string", "description": "HTML content to analyze. Also accepts `\"content\"` as an alias (MCP compatibility)." }, "site_url": { "type": [ "string", "null" ], "description": "Site URL for context (e.g., \"https://crawlkit.app\")." } } }, "CheckResponse": { "type": "object", "required": [ "issues", "score", "label", "breakdown", "top_impact", "recommendation" ], "properties": { "breakdown": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionScoreDto" } }, "coaching_context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CoachingContext" } ] }, "crawl_duration_secs": { "type": [ "number", "null" ], "format": "double", "description": "Crawl duration in seconds (0.0 for inline content checks)" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/IssueDto" } }, "label": { "type": "string" }, "recommendation": { "type": "string" }, "score": { "type": "integer", "format": "int32", "minimum": 0 }, "top_impact": { "type": "string" } } }, "CheckUrlRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "ClassificationDto": { "type": "object", "required": [ "taxonomy_id", "taxonomy_name", "confidence", "method" ], "properties": { "confidence": { "type": "number", "format": "double" }, "method": { "type": "string" }, "taxonomy_id": { "type": "string" }, "taxonomy_name": { "type": "string" } } }, "ClassifyRequest": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" }, "url": { "type": "string" } } }, "ClassifyResponse": { "type": "object", "required": [ "classifications", "quality_profile" ], "properties": { "classifications": { "type": "array", "items": { "$ref": "#/components/schemas/ClassificationDto" } }, "quality_profile": { "$ref": "#/components/schemas/QualityProfileDto" } } }, "ClientDetailResponse": { "type": "object", "required": [ "client", "sites" ], "properties": { "client": { "$ref": "#/components/schemas/ClientDto" }, "sites": { "type": "array", "items": { "$ref": "#/components/schemas/SiteResponse" } } } }, "ClientDto": { "type": "object", "description": "Response DTO for a client account managed by an agency.", "required": [ "id", "client_account_id", "name", "sites_count", "total_issues", "total_pages", "status", "added_at" ], "properties": { "added_at": { "type": "string", "format": "date-time" }, "avg_health_score": { "type": [ "number", "null" ], "format": "double" }, "client_account_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "last_audit": { "type": [ "string", "null" ], "format": "date-time" }, "name": { "type": "string" }, "sites_count": { "type": "integer", "format": "int64" }, "status": { "type": "string" }, "total_issues": { "type": "integer", "format": "int64" }, "total_pages": { "type": "integer", "format": "int64" } } }, "ClientListResponse": { "type": "object", "required": [ "clients", "total" ], "properties": { "clients": { "type": "array", "items": { "$ref": "#/components/schemas/ClientDto" } }, "total": { "type": "integer", "format": "int64" } } }, "CoachingContext": { "type": "object", "description": "Contextual coaching data to help AI assistants provide better SEO guidance.", "required": [ "metadata_summary" ], "properties": { "competitor_context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompetitorContextDto", "description": "Competitor SERP context for the matched keyword" } ] }, "framework": { "type": [ "string", "null" ], "description": "Detected framework (e.g., \"NextJs { app_router: true }\")" }, "keyword_context": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/KeywordContextDto", "description": "Keyword targeting context for the analyzed page" } ] }, "link_health": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LinkHealthDto", "description": "Link graph health summary (DSOF §3.2 targets)" } ] }, "link_suggestions": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/LinkSuggestionCoachingDto" }, "description": "Internal link suggestions for the analyzed page" }, "metadata_summary": { "$ref": "#/components/schemas/MetadataSummary", "description": "Summary of page metadata presence and quality" }, "structured_data_suggestions": { "type": "array", "items": { "type": "string" }, "description": "Suggested structured data types for this page" } } }, "ColumnInfo": { "type": "object", "description": "Column metadata", "required": [ "name", "data_type" ], "properties": { "data_type": { "type": "string" }, "name": { "type": "string" } } }, "CommentRequest": { "type": "object", "description": "Request to add a comment to a governance policy.", "required": [ "author_id", "comment" ], "properties": { "author_id": { "type": "string" }, "comment": { "type": "string" } } }, "CommunityDiscoveryRequest": { "type": "object", "properties": { "brand_graph": { "description": "Free-form brand graph. Known sections (identity, audience, strategy,\ntopic_alignment/topics, feedback_learning) are mined for discovery and\nICP terms; unknown shapes are ignored rather than rejected." }, "brand_graph_id": { "description": "Opaque brand-graph identifier (callers send either an integer or a\nstring id). Accepted for traceability; the graph body in `brand_graph`\nis what influences discovery." }, "channel_filters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChannelFilter" } }, "channel_search_parameters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DiscoverySearchParameters", "description": "Alternate key for `search_parameters`; both are accepted and merged\n(`search_parameters` wins on conflicting scalar knobs)." } ] }, "content": { "type": [ "string", "null" ], "description": "Free-form content excerpt; keyword tokens are extracted into the\ndiscovery terms." }, "filters": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/ChannelFilter" }, "description": "Alternate key for `channel_filters`; OpenRecipe sends both with the\nsame content. Both are accepted and merged." }, "icp_description": { "type": [ "string", "null" ], "description": "Ideal-customer-profile description. Feeds both term discovery and the\nICP-overlap component of community scoring." }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "Explicit search terms. Optional when enough context is supplied via\n`content`, `brand_graph`, `icp_description` or search parameters." }, "limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_subscribers": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "platform": { "type": [ "string", "null" ], "description": "Singular spelling sent by OpenRecipe (`\"platform\": \"reddit\"`). This\nendpoint is Reddit-only; the field is accepted for forward\ncompatibility and ignored otherwise." }, "platforms": { "type": [ "array", "null" ], "items": { "type": "string" } }, "provider_order": { "type": "array", "items": { "type": "string" }, "description": "Optional source-selector from the OpenRecipe Reddit source picker.\nGates which internal CrawlKit sources run: empty (the default) keeps the\ncurrent behavior (all CrawlKit sources). `\"crawlkit\"` selects the\nCrawlKit archive sources; `\"official_reddit\"` is a no-op here (CrawlKit\nhas no official Reddit source — that selector applies at the\nreddit-intelligence backfill layer)." }, "search_parameters": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DiscoverySearchParameters" } ] }, "source_url": { "type": [ "string", "null" ], "description": "Brand/site URL; host tokens enrich the discovery terms." }, "target_kpi": { "type": [ "string", "null" ], "description": "KPI the caller optimizes for: engagement | leads | citations |\nsentiment. Selects a relevance-weight profile (see\n`KPI_WEIGHT_PROFILES` in the service)." } } }, "CommunityDiscoveryResponse": { "type": "object", "required": [ "communities", "total_scanned" ], "properties": { "communities": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveredCommunity" } }, "total_scanned": { "type": "integer", "format": "int32", "minimum": 0 } } }, "CompareRatesResponse": { "type": "object", "required": [ "comparisons" ], "properties": { "comparisons": { "type": "array", "items": { "$ref": "#/components/schemas/ComparisonRow" } }, "market_stats": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketStats" } ] } } }, "CompareRequest": { "type": "object", "required": [ "dataset_id_a", "dataset_id_b" ], "properties": { "dataset_id_a": { "type": "string", "format": "uuid" }, "dataset_id_b": { "type": "string", "format": "uuid" } } }, "CompareResponse": { "type": "object", "required": [ "profile_a", "profile_b", "diffs" ], "properties": { "diffs": {}, "profile_a": { "$ref": "#/components/schemas/ProfileResponse" }, "profile_b": { "$ref": "#/components/schemas/ProfileResponse" } } }, "ComparisonRow": { "type": "object", "required": [ "hospital_name" ], "properties": { "cash_price": { "type": [ "number", "null" ], "format": "double" }, "gross_charge": { "type": [ "number", "null" ], "format": "double" }, "hospital_city": { "type": [ "string", "null" ] }, "hospital_name": { "type": "string" }, "hospital_state": { "type": [ "string", "null" ] }, "market_median": { "type": [ "number", "null" ], "format": "double" }, "median_allowed": { "type": [ "number", "null" ], "format": "double" }, "negotiated_rate": { "type": [ "number", "null" ], "format": "double" }, "payer_name": { "type": [ "string", "null" ] }, "pct_of_medicare": { "type": [ "number", "null" ], "format": "double" }, "source_date": { "type": [ "string", "null" ] } } }, "CompetitorAnalysis": { "type": "object", "required": [ "keyword", "competitors" ], "properties": { "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/SerpCompetitor" } }, "keyword": { "type": "string" } } }, "CompetitorContextDto": { "type": "object", "description": "Competitor SERP positions for a keyword.", "required": [ "keyword", "top_competitors" ], "properties": { "keyword": { "type": "string", "description": "The keyword being compared" }, "top_competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorPositionDto" }, "description": "Top competitors ranking for this keyword (up to 3)" } } }, "CompetitorDto": { "type": "object", "required": [ "id", "domain", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "label": { "type": [ "string", "null" ] } } }, "CompetitorEntry": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "label": { "type": [ "string", "null" ] } } }, "CompetitorPositionDto": { "type": "object", "description": "A single competitor's SERP position data.", "required": [ "domain", "position" ], "properties": { "domain": { "type": "string" }, "position": { "type": "integer", "format": "int32", "minimum": 0 }, "schema_types": { "type": "array", "items": { "type": "string" } }, "word_count": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "CompetitorsQuery": { "type": "object", "required": [ "site_id", "keyword" ], "properties": { "keyword": { "type": "string" }, "site_id": { "type": "string", "format": "uuid" } } }, "CompetitorsUpdatedResponse": { "type": "object", "required": [ "added", "removed" ], "properties": { "added": { "type": "integer", "minimum": 0 }, "removed": { "type": "integer", "minimum": 0 } } }, "CompressRequest": { "type": "object", "description": "Request to compress or decompress a file", "required": [ "input_path", "algorithm", "direction" ], "properties": { "algorithm": { "type": "string", "description": "\"gzip\", \"zstd\", or \"zip\"" }, "direction": { "type": "string", "description": "\"compress\" or \"decompress\"" }, "input_path": { "type": "string" }, "output_path": { "type": [ "string", "null" ] } } }, "CompressResponse": { "type": "object", "description": "Response from compress/decompress operation", "required": [ "output_path", "original_size", "result_size" ], "properties": { "original_size": { "type": "integer", "format": "int64", "minimum": 0 }, "output_path": { "type": "string" }, "result_size": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ComputeScoreRequest": { "type": "object", "required": [ "model_type", "target_type", "target_id" ], "properties": { "model_type": { "type": "string" }, "site_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Injected by site_resolver middleware (replaces site_url)." }, "site_url": { "type": [ "string", "null" ] }, "target_id": { "type": "string" }, "target_type": { "type": "string" } } }, "ConfidenceIntervalDto": { "type": "object", "required": [ "lower", "upper", "level" ], "properties": { "level": { "type": "number", "format": "double" }, "lower": { "type": "number", "format": "double" }, "upper": { "type": "number", "format": "double" } } }, "ConsentResponse": { "type": "object", "required": [ "id", "consent_status", "license_type", "created_at", "updated_at" ], "properties": { "consent_status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "license_type": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "robots_txt_allows": { "type": [ "boolean", "null" ] }, "tos_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "url": { "type": [ "string", "null" ] } } }, "ContaminatedItem": { "type": "object", "description": "A single contaminated text item.", "required": [ "index", "benchmark", "overlap_score", "matching_fragment", "method" ], "properties": { "benchmark": { "type": "string" }, "index": { "type": "integer", "minimum": 0 }, "matching_fragment": { "type": "string" }, "method": { "type": "string" }, "overlap_score": { "type": "number", "format": "double" } } }, "ContentExtractionRequest": { "type": "object", "required": [ "url" ], "properties": { "extract_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExtractionOptions" } ] }, "url": { "type": "string" } } }, "ContentExtractionResponse": { "type": "object", "required": [ "url", "title", "content", "keywords", "word_count", "reading_time_minutes", "content_type", "language", "extraction_metadata" ], "properties": { "author": { "type": [ "string", "null" ] }, "content": { "type": "string" }, "content_type": { "type": "string" }, "extraction_metadata": { "$ref": "#/components/schemas/ExtractionMetadata" }, "extraction_quality_score": { "type": "number", "format": "float", "description": "Prose-quality score in `[0, 1]` for the extracted body (0.0 when unknown)." }, "keywords": { "type": "array", "items": { "type": "string" } }, "language": { "type": "string" }, "published_at": { "type": [ "string", "null" ] }, "reading_time_minutes": { "type": "integer", "format": "int32", "minimum": 0 }, "summary": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "url": { "type": "string" }, "word_count": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ContentGap": { "type": "object", "description": "A keyword where competitors rank well but we don't.", "required": [ "keyword", "competitor_count", "best_competitor_position", "best_competitor_domain", "opportunity_score" ], "properties": { "best_competitor_domain": { "type": "string" }, "best_competitor_position": { "type": "integer", "format": "int32", "minimum": 0 }, "competitor_count": { "type": "integer", "minimum": 0 }, "keyword": { "type": "string" }, "monthly_volume": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "opportunity_score": { "type": "number", "format": "double", "description": "opportunity = volume * (1 / best_position) as relevance proxy" } } }, "CostRecordResponse": { "type": "object", "required": [ "id", "resource_type", "quantity", "unit_cost", "total_cost", "currency", "recorded_at" ], "properties": { "currency": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "pipeline_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "quantity": { "type": "number", "format": "double" }, "recorded_at": { "type": "string", "format": "date-time" }, "resource_type": { "type": "string" }, "step_index": { "type": [ "integer", "null" ], "format": "int32" }, "total_cost": { "type": "number", "format": "double" }, "unit_cost": { "type": "number", "format": "double" } } }, "CostSummaryResponse": { "type": "object", "required": [ "resource_type", "total_quantity", "total_cost", "record_count" ], "properties": { "record_count": { "type": "integer", "format": "int64" }, "resource_type": { "type": "string" }, "total_cost": { "type": "number", "format": "double" }, "total_quantity": { "type": "number", "format": "double" } } }, "CrawlBudgetDto": { "type": "object", "description": "Budget constraints for a crawl job.", "properties": { "js_rendering": { "type": "boolean" }, "max_concurrency": { "type": "integer", "format": "int32", "minimum": 0 }, "max_duration_secs": { "type": "integer", "format": "int32", "minimum": 0 }, "max_pages": { "type": "integer", "format": "int32", "minimum": 0 } } }, "CrawlProgressDto": { "type": "object", "description": "Progress counters for a running crawl.", "required": [ "pages_crawled", "pages_queued", "pages_failed", "pages_skipped", "bytes_downloaded", "elapsed_secs" ], "properties": { "bytes_downloaded": { "type": "integer", "format": "int64", "minimum": 0 }, "elapsed_secs": { "type": "number", "format": "double" }, "pages_crawled": { "type": "integer", "format": "int32", "minimum": 0 }, "pages_failed": { "type": "integer", "format": "int32", "minimum": 0 }, "pages_queued": { "type": "integer", "format": "int32", "minimum": 0 }, "pages_skipped": { "type": "integer", "format": "int32", "minimum": 0 } } }, "CreateApiTokenRequest": { "type": "object", "required": [ "name" ], "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Tenant account id to create the token for. Defaults to the authenticated request account." }, "environment": { "type": [ "string", "null" ], "description": "Token environment/prefix: `live` (default) or `test`." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Optional expiration timestamp." }, "name": { "type": "string", "description": "Human-readable token name shown in tenant settings." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Optional authorization scopes. Empty means full account access for backwards compatibility." } } }, "CreateApiTokenResponse": { "type": "object", "required": [ "token", "token_info" ], "properties": { "token": { "type": "string", "description": "Plaintext API token. It is returned once and never stored by CrawlKit." }, "token_info": { "$ref": "#/components/schemas/ApiTokenSummary" } } }, "CreateAssetDefinitionRequest": { "type": "object", "required": [ "name", "source_config" ], "properties": { "asset_type": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "quality_gate": {}, "schedule_cron": { "type": [ "string", "null" ] }, "source_config": {}, "transform_pipeline_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "CreateAssetRequest": { "type": "object", "required": [ "name", "asset_type" ], "properties": { "asset_type": { "type": "string" }, "created_by_pipeline_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_by_step_index": { "type": [ "integer", "null" ], "format": "int32" }, "metadata": {}, "name": { "type": "string" }, "source_uri": { "type": [ "string", "null" ] } } }, "CreateCampaignRequest": { "type": "object", "required": [ "name", "stages" ], "properties": { "name": { "type": "string" }, "scoring_rules": {}, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignStageDto" } } } }, "CreateConsentRequest": { "type": "object", "required": [ "consent_status" ], "properties": { "consent_status": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "license_type": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "robots_txt_allows": { "type": [ "boolean", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "CreateCostRecordRequest": { "type": "object", "required": [ "resource_type", "quantity", "unit_cost" ], "properties": { "pipeline_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "quantity": { "type": "number", "format": "double" }, "resource_type": { "type": "string" }, "step_index": { "type": [ "integer", "null" ], "format": "int32" }, "unit_cost": { "type": "number", "format": "double" } } }, "CreateDataSourceRequest": { "type": "object", "required": [ "source_type", "source_name", "source_url" ], "properties": { "expected_update_frequency": { "type": [ "string", "null" ] }, "file_format": { "type": [ "string", "null" ] }, "source_name": { "type": "string" }, "source_type": { "type": "string" }, "source_url": { "type": "string" } } }, "CreateDatasetRequest": { "type": "object", "description": "Request to create a new dataset.", "required": [ "name", "columns" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetColumnDto" } }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "source": { "type": [ "string", "null" ] } } }, "CreateDealRequest": { "type": "object", "required": [ "title" ], "properties": { "close_date": { "type": [ "string", "null" ], "format": "date" }, "currency": { "type": "string" }, "lead_id": { "type": [ "string", "null" ], "format": "uuid" }, "probability": { "type": [ "number", "null" ], "format": "double" }, "stage": { "type": "string" }, "title": { "type": "string" }, "value_cents": { "type": [ "integer", "null" ], "format": "int64" } } }, "CreateDestinationRequest": { "type": "object", "required": [ "sink_type", "name", "config" ], "properties": { "config": {}, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": "string" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "signal_types": { "type": [ "array", "null" ], "items": { "type": "string" } }, "sink_type": { "type": "string" } } }, "CreateDocumentRequest": { "type": "object", "description": "Request to create a content document.", "required": [ "site_id", "title", "content_json" ], "properties": { "content_json": { "description": "Plate.js document JSON" }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "site_id": { "type": "string", "format": "uuid" }, "slug": { "type": [ "string", "null" ] }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" } } }, "CreateEdgeRequest": { "type": "object", "required": [ "parent_asset_id", "child_asset_id" ], "properties": { "child_asset_id": { "type": "string", "format": "uuid" }, "parent_asset_id": { "type": "string", "format": "uuid" }, "pipeline_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "transformation": { "type": [ "string", "null" ] } } }, "CreateEtlPipelineRequest": { "type": "object", "description": "Request to create a new ETL pipeline", "required": [ "name", "steps" ], "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "schedule": { "type": [ "string", "null" ] }, "site_url": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStepDto" } } } }, "CreateExperimentRequest": { "type": "object", "required": [ "action_type", "action_description", "target_urls", "target_metric", "baseline_value", "expected_direction" ], "properties": { "action_description": { "type": "string" }, "action_type": { "type": "string" }, "baseline_value": { "type": "number", "format": "double" }, "expected_direction": { "type": "string" }, "observation_window_days": { "type": "integer", "format": "int32" }, "site_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Injected by site_resolver middleware from site_url." }, "site_url": { "type": [ "string", "null" ], "description": "Site URL for site resolver middleware." }, "target_metric": { "type": "string" }, "target_urls": { "type": "array", "items": { "type": "string" } } } }, "CreateIncidentRequest": { "type": "object", "description": "Request to create an incident.", "required": [ "incident_type", "source_id", "source_type", "severity" ], "properties": { "description": { "type": [ "string", "null" ] }, "detected_at": { "type": [ "string", "null" ] }, "incident_type": { "type": "string" }, "severity": { "type": "string" }, "source_id": { "type": "string" }, "source_type": { "type": "string" } } }, "CreateJobRequest": { "type": "object", "description": "Request to create a distributed crawl job.\n\nEither `site_id` (a pre-registered site) OR `url` (auto-resolved/created\ninternally) is required. When `site_id` is supplied but does not exist, the\nrequest fails with a structured 422 `site_not_found`; when neither is\nsupplied it fails with 422 `site_or_url_required`.", "properties": { "budget": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CrawlBudgetDto", "description": "Budget constraints" } ] }, "recrawl_policy": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RecrawlPolicyDto", "description": "Re-crawl policy" } ] }, "scrape_options": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DeepScrapeOptions", "description": "Optional deep/sitemap scrape options. Absent or all-off → today's\nsingle-page-budget crawl. When supplied, the resolved page/depth budget\nand JS-render flags are carried onto the job budget." } ] }, "site_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Pre-registered site to crawl. Optional when `url` is supplied." }, "stealth_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StealthConfigDto", "description": "Stealth/proxy configuration (overrides site-level defaults)" } ] }, "strategy_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StrategyConfigDto", "description": "Inline strategy config (overrides strategy_id)" } ] }, "strategy_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Named strategy ID to use (mutually exclusive with `strategy_config`)" }, "url": { "type": [ "string", "null" ], "description": "Site URL to crawl. When supplied without `site_id`, the site is\nauto-resolved (reused by domain) or created for the account." }, "webhook_secret": { "type": [ "string", "null" ], "description": "HMAC-SHA256 signing secret for the webhook. Falls back to the\nplatform-level CRAWLKIT_WEBHOOK_SECRET when omitted." }, "webhook_url": { "type": [ "string", "null" ], "description": "Optional webhook target: receives an HMAC-signed `crawl.completed`\nPOST when the job finishes. Must be a public http(s) URL (SSRF-checked)." } } }, "CreateLeadRequest": { "type": "object", "properties": { "company_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "enrichment_data": {}, "source": { "type": "string" } } }, "CreateMonitorRequest": { "type": "object", "required": [ "name" ], "properties": { "authors": { "type": "array", "items": { "type": "string" } }, "companies": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "industries": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "monitor_type": { "type": "string" }, "name": { "type": "string" }, "priority": { "type": "string" }, "seniority_filter": { "type": "array", "items": { "type": "string" } }, "stealth_config": {} } }, "CreatePipelineRequest": { "type": "object", "description": "Request to create a new enrichment pipeline.", "required": [ "name", "steps" ], "properties": { "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "pipeline_kind": { "type": [ "string", "null" ] }, "schedule": { "type": [ "string", "null" ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStepDto" } } } }, "CreatePolicyRequest": { "type": "object", "description": "Request to create a governance policy.", "required": [ "policy_type", "resource_id", "resource_type", "requested_by" ], "properties": { "justification": { "type": [ "string", "null" ] }, "policy_type": { "type": "string" }, "requested_by": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" } } }, "CreateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "allowed_origins": { "type": [ "array", "null" ], "items": { "type": "string" } }, "config": {}, "name": { "type": "string" } } }, "CreateRowRequest": { "type": "object", "description": "Request to create a row in a dataset.", "required": [ "data" ], "properties": { "data": {} } }, "CreateScheduledAuditRequest": { "type": "object", "required": [ "site_id" ], "properties": { "frequency": { "$ref": "#/components/schemas/AuditScheduleFrequency" }, "max_pages": { "type": "integer", "format": "int32" }, "site_id": { "type": "string", "format": "uuid" } } }, "CreateSchemaRequest": { "type": "object", "required": [ "schema_name", "json_schema" ], "properties": { "json_schema": {}, "schema_name": { "type": "string" } } }, "CreateSiteRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" }, "framework": { "type": [ "string", "null" ] } } }, "CreateSpiderRequest": { "type": "object", "description": "Request to create a new spider definition.", "required": [ "name", "kind" ], "properties": { "definition": { "description": "Full definition JSON (overrides individual fields)." }, "description": { "type": [ "string", "null" ] }, "kind": { "type": "string" }, "name": { "type": "string" }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpiderScopeDto", "description": "Spider scope: start URLs, allowed/denied patterns." } ] } } }, "CreateStrategyRequest": { "type": "object", "description": "Request to create or update a named strategy.", "required": [ "name", "config" ], "properties": { "config": { "$ref": "#/components/schemas/StrategyConfigDto" }, "name": { "type": "string" } } }, "CreateTemplateRequest": { "type": "object", "description": "Request body for creating a workflow template.", "required": [ "template" ], "properties": { "template": { "type": "object", "description": "The full WorkflowTemplate to store (serialized as JSONB)." } } }, "CsvKeywordRow": { "type": "object", "required": [ "query" ], "properties": { "difficulty": { "type": [ "integer", "null" ], "format": "int32" }, "priority": { "type": [ "string", "null" ] }, "query": { "type": "string" }, "search_volume": { "type": [ "integer", "null" ], "format": "int32" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "CustomDomainDto": { "type": "object", "required": [ "id", "domain", "verification_cname", "routing_cname_target", "verification_status", "check_count", "created_at" ], "properties": { "check_count": { "type": "integer", "format": "int32" }, "check_error": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "dns_verified_at": { "type": [ "string", "null" ], "format": "date-time" }, "domain": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "instructions": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DomainInstructions" } ] }, "last_check_at": { "type": [ "string", "null" ], "format": "date-time" }, "routing_cname_target": { "type": "string" }, "ssl_provisioned_at": { "type": [ "string", "null" ], "format": "date-time" }, "verification_cname": { "type": "string" }, "verification_status": { "type": "string" } } }, "DailyMetricDto": { "type": "object", "required": [ "date", "event_count", "unique_users", "unique_sessions" ], "properties": { "date": { "type": "string", "format": "date" }, "event_count": { "type": "integer", "format": "int64" }, "unique_sessions": { "type": "integer", "format": "int64" }, "unique_users": { "type": "integer", "format": "int64" } } }, "DashboardResponse": { "type": "object", "required": [ "sites_count", "gsc_connected_count", "total_issues", "total_pages", "keywords_count", "pending_feedback", "recent_audits", "issue_severity_distribution" ], "properties": { "avg_health_score": { "type": [ "number", "null" ], "format": "double" }, "gsc_connected_count": { "type": "integer", "format": "int64" }, "issue_severity_distribution": { "$ref": "#/components/schemas/IssueSeverityDistribution" }, "keywords_count": { "type": "integer", "format": "int64" }, "pending_feedback": { "type": "integer", "format": "int64" }, "recent_audits": { "type": "array", "items": { "$ref": "#/components/schemas/RecentAuditDto" } }, "sites_count": { "type": "integer", "format": "int64" }, "total_issues": { "type": "integer", "format": "int64" }, "total_pages": { "type": "integer", "format": "int64" } } }, "DataSourceDetail": { "type": "object", "required": [ "id", "source_type", "source_name", "source_url", "status" ], "properties": { "error_message": { "type": [ "string", "null" ] }, "expected_update_frequency": { "type": [ "string", "null" ] }, "file_format": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "last_checked_at": { "type": [ "string", "null" ] }, "last_ingested_at": { "type": [ "string", "null" ] }, "record_count": { "type": [ "integer", "null" ], "format": "int64" }, "source_name": { "type": "string" }, "source_type": { "type": "string" }, "source_url": { "type": "string" }, "status": { "type": "string" } } }, "DataSourceFreshness": { "type": "object", "required": [ "source_type", "source_name", "status" ], "properties": { "last_ingested_at": { "type": [ "string", "null" ] }, "record_count": { "type": [ "integer", "null" ], "format": "int64" }, "source_name": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string" } } }, "DatasetColumnDto": { "type": "object", "description": "A column in a dataset schema.", "required": [ "name", "column_type" ], "properties": { "column_type": { "type": "string" }, "default_value": {}, "name": { "type": "string" }, "required": { "type": "boolean" } } }, "DatasetListResponse": { "type": "object", "description": "List of datasets.", "required": [ "datasets", "total" ], "properties": { "datasets": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "DatasetResponse": { "type": "object", "description": "Response for a dataset.", "required": [ "id", "name", "status", "columns", "row_count", "created_at", "updated_at" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetColumnDto" } }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "row_count": { "type": "integer", "format": "int64" }, "source": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DatasetRowResponse": { "type": "object", "description": "Response for a dataset row.", "required": [ "id", "dataset_id", "data", "enrichment_status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "data": {}, "dataset_id": { "type": "string", "format": "uuid" }, "enrichment_status": {}, "id": { "type": "string", "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DatasetStatsResponse": { "type": "object", "description": "Dataset statistics.", "required": [ "dataset_id", "row_count", "column_count", "enrichment_coverage", "sources" ], "properties": { "column_count": { "type": "integer", "minimum": 0 }, "dataset_id": { "type": "string", "format": "uuid" }, "enrichment_coverage": { "type": "number", "format": "double" }, "row_count": { "type": "integer", "format": "int64" }, "sources": { "type": "array", "items": { "type": "string" } } } }, "DealResponse": { "type": "object", "required": [ "id", "title", "currency", "stage", "seo_attribution", "created_at", "updated_at" ], "properties": { "close_date": { "type": [ "string", "null" ], "format": "date" }, "created_at": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "lead_id": { "type": [ "string", "null" ], "format": "uuid" }, "probability": { "type": [ "number", "null" ], "format": "double" }, "seo_attribution": {}, "stage": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "value_cents": { "type": [ "integer", "null" ], "format": "int64" } } }, "DecontaminateRequest": { "type": "object", "description": "Request to check texts for benchmark contamination.", "required": [ "texts" ], "properties": { "benchmarks": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkId" }, "description": "Which benchmarks to check against (default: all built-in)" }, "method": { "$ref": "#/components/schemas/DecontaminationMethod", "description": "Decontamination method (default: ngram)" }, "ngram_size": { "type": "integer", "description": "N-gram size for overlap detection (default: 8)", "minimum": 0 }, "texts": { "type": "array", "items": { "type": "string" }, "description": "Texts to check for contamination (max 10,000)" }, "threshold": { "type": "number", "format": "double", "description": "N-gram overlap threshold (default: 0.8)" } } }, "DecontaminateResponse": { "type": "object", "description": "Response from a decontamination check.", "required": [ "total_checked", "contaminated_count", "contamination_rate", "contaminated_indices", "benchmarks_checked" ], "properties": { "benchmarks_checked": { "type": "array", "items": { "$ref": "#/components/schemas/BenchmarkInfo" } }, "contaminated_count": { "type": "integer", "minimum": 0 }, "contaminated_indices": { "type": "array", "items": { "$ref": "#/components/schemas/ContaminatedItem" } }, "contamination_rate": { "type": "number", "format": "double" }, "total_checked": { "type": "integer", "minimum": 0 } } }, "DecontaminationMethod": { "type": "string", "description": "Available decontamination methods.", "enum": [ "ngram", "exact_match", "fuzzy", "all" ] }, "DedupRequest": { "type": "object", "required": [ "dataset_id" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "jaccard_threshold": { "type": [ "number", "null" ], "format": "double" }, "ngram_size": { "type": [ "integer", "null" ], "format": "int64" }, "num_hashes": { "type": [ "integer", "null" ], "format": "int64" } } }, "DedupResponse": { "type": "object", "required": [ "dataset_id", "unique_count", "duplicate_count", "duplicates" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "duplicate_count": { "type": "integer", "format": "int64" }, "duplicates": { "type": "array", "items": { "$ref": "#/components/schemas/DuplicatePair" } }, "unique_count": { "type": "integer", "format": "int64" } } }, "DeepScrapeOptions": { "type": "object", "description": "Serde DTO mirroring the FE/PHP `scrape_options` payload. All fields default\nto OFF so an absent or empty `scrape_options` yields the single-page default.", "properties": { "follow_pagination": { "type": "boolean" }, "infinite_scroll": { "type": "boolean" }, "max_depth": { "type": [ "integer", "null" ], "minimum": 0 }, "max_pages": { "type": [ "integer", "null" ], "minimum": 0 }, "render_mode": { "type": [ "string", "null" ], "description": "Render mode string: `\"static\" | \"auto\" | \"js\"`. Unknown/absent → `static`." }, "use_sitemap": { "type": "boolean" } } }, "DeleteApiTokenResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeleteBriefResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeleteDomainResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeleteScheduledAuditResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeleteSiteResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DequeueRequest": { "type": "object", "description": "Request to dequeue items (claim for processing).", "required": [ "queue_name" ], "properties": { "batch_size": { "type": "integer", "format": "int32", "minimum": 0 }, "lock_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "queue_name": { "type": "string" } } }, "DequeueResponse": { "type": "object", "description": "Response for dequeue operation.", "required": [ "items", "claimed" ], "properties": { "claimed": { "type": "integer", "minimum": 0 }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueueItemResponse" } } } }, "DescribeRequest": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "DestinationResponse": { "type": "object", "required": [ "id", "account_id", "sink_type", "name", "config", "signal_types", "enabled", "created_at", "updated_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "config": {}, "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "project_id": { "type": [ "string", "null" ], "format": "uuid" }, "signal_types": { "type": "array", "items": { "type": "string" } }, "sink_type": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DiagnoseRequest": { "type": "object", "description": "Request to diagnose a pipeline and propose a fix.", "required": [ "pipeline_id", "error_context" ], "properties": { "error_context": {}, "pipeline_id": { "type": "string", "format": "uuid" } } }, "DiagnoseResponse": { "type": "object", "description": "Response from a diagnose operation.", "required": [ "patch" ], "properties": { "patch": { "$ref": "#/components/schemas/PatchResponse" } } }, "DimensionScoreDto": { "type": "object", "description": "Per-dimension scoring breakdown.", "required": [ "dimension", "description", "score", "weight", "issues", "contribution" ], "properties": { "contribution": { "type": "number", "format": "double" }, "description": { "type": "string" }, "dimension": { "type": "string" }, "issues": { "type": "integer", "minimum": 0 }, "score": { "type": "integer", "format": "int32", "minimum": 0 }, "weight": { "type": "number", "format": "double" } } }, "DiscoveredCommunity": { "type": "object", "required": [ "subreddit", "display_name", "description", "subscribers", "active_users", "relevance_score", "competitive_saturation", "posting_norms", "top_keywords", "sentiment_baseline", "activity_level" ], "properties": { "active_users": { "type": "integer", "format": "int32", "minimum": 0 }, "activity_level": { "type": "string" }, "competitive_saturation": { "type": "number", "format": "double" }, "description": { "type": "string" }, "display_name": { "type": "string" }, "posting_norms": { "$ref": "#/components/schemas/PostingNorms" }, "relevance_score": { "type": "number", "format": "double" }, "sentiment_baseline": { "type": "string" }, "subreddit": { "type": "string" }, "subscribers": { "type": "integer", "format": "int64", "minimum": 0 }, "top_keywords": { "type": "array", "items": { "type": "string" } } } }, "DiscoveredSitemap": { "type": "object", "description": "One discovered sitemap and what it contains.", "required": [ "url", "url_count", "child_sitemaps", "sample_urls" ], "properties": { "child_sitemaps": { "type": "array", "items": { "type": "string" }, "description": "Child sitemap URLs when this is a sitemap index. These are reported\nbut not fetched — call this endpoint again with a child URL to expand." }, "sample_urls": { "type": "array", "items": { "type": "string" }, "description": "First page URLs from the sitemap (capped sample)." }, "url": { "type": "string", "description": "The sitemap URL that was fetched and parsed." }, "url_count": { "type": "integer", "description": "Number of page URLs listed in this sitemap.", "minimum": 0 } } }, "DiscoverySearchParameters": { "type": "object", "description": "Search-parameter envelope accepted under both `search_parameters` and\n`channel_search_parameters` (OpenRecipe sends the same object under both\nkeys). Knobs that have a CrawlKit equivalent (limit, min/max subscribers,\nquery/include/exclude terms, target_kpi) are honored; presentation-only\nknobs (sort_by, min_affinity_score, connector flags) are accepted so the\npayload round-trips, but ranking always returns relevance-ordered results.", "properties": { "crawlkit_required": { "type": [ "boolean", "null" ], "default": null }, "exclude_terms": { "type": "array", "items": { "type": "string" }, "default": [] }, "include_terms": { "type": "array", "items": { "type": "string" }, "default": [] }, "limit": { "type": [ "integer", "null" ], "format": "int32", "default": null, "minimum": 0 }, "max_subscribers": { "type": [ "number", "null" ], "format": "double", "default": null }, "min_affinity_score": { "type": [ "number", "null" ], "format": "double", "default": null }, "min_subscribers": { "type": [ "number", "null" ], "format": "double", "description": "Accepted as a float because upstream normalization may emit either\ninteger or float JSON numbers.", "default": null }, "official_connector_required": { "type": [ "boolean", "null" ], "default": null }, "platform": { "type": [ "string", "null" ], "default": null }, "query_terms": { "type": "array", "items": { "type": "string" }, "default": [] }, "sort_by": { "type": [ "string", "null" ], "default": null }, "target_kpi": { "type": [ "string", "null" ], "description": "engagement | leads | citations | sentiment", "default": null } } }, "DiscrepanciesResponse": { "type": "object", "required": [ "discrepancies" ], "properties": { "discrepancies": { "type": "array", "items": { "$ref": "#/components/schemas/DiscrepancyRow" } } } }, "DiscrepancyRow": { "type": "object", "required": [ "code", "hospital_name", "payer_name" ], "properties": { "absolute_difference": { "type": [ "number", "null" ], "format": "double" }, "code": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "hospital_name": { "type": "string" }, "hospital_reported_rate": { "type": [ "number", "null" ], "format": "double" }, "insurer_reported_rate": { "type": [ "number", "null" ], "format": "double" }, "payer_name": { "type": "string" }, "pct_difference": { "type": [ "number", "null" ], "format": "double" } } }, "DismissResponse": { "type": "object", "description": "Dismiss request (just the alert ID in path).", "required": [ "dismissed" ], "properties": { "dismissed": { "type": "boolean" } } }, "DnsAuditRequest": { "type": "object", "required": [ "site_id" ], "properties": { "domain": { "type": [ "string", "null" ] }, "site_id": { "type": "string", "format": "uuid" } } }, "DnsAuditResponse": { "type": "object", "required": [ "domain", "resolves", "canonical", "ssl", "www_redirect", "https_redirect", "email_auth", "records", "issues", "recommendations" ], "properties": { "canonical": { "$ref": "#/components/schemas/CanonicalDto" }, "domain": { "type": "string" }, "email_auth": { "$ref": "#/components/schemas/EmailAuthDto" }, "https_redirect": { "$ref": "#/components/schemas/RedirectDto" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/DnsIssueDto" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "records": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "propertyNames": { "type": "string" } }, "resolves": { "type": "boolean" }, "ssl": { "$ref": "#/components/schemas/SslDto" }, "www_redirect": { "$ref": "#/components/schemas/RedirectDto" } } }, "DnsIssueDto": { "type": "object", "required": [ "category", "severity", "description" ], "properties": { "category": { "type": "string" }, "description": { "type": "string" }, "remediation": { "type": [ "string", "null" ] }, "severity": { "type": "string" } } }, "DocumentResponse": { "type": "object", "description": "Content document response DTO.", "required": [ "id", "site_id", "title", "content_json", "target_keywords", "status", "created_at", "updated_at" ], "properties": { "content_json": {}, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "published_url": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "seo_score": { "type": [ "integer", "null" ], "format": "int32" }, "site_id": { "type": "string", "format": "uuid" }, "slug": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "target_keywords": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "DocumentStatus": { "type": "string", "description": "Content document status.", "enum": [ "draft", "review", "approved", "scheduled", "published" ] }, "DomainInstructions": { "type": "object", "required": [ "step_1_verification", "step_2_routing", "note" ], "properties": { "note": { "type": "string" }, "step_1_verification": { "type": "string" }, "step_2_routing": { "type": "string" } } }, "DomainListResponse": { "type": "object", "required": [ "domains" ], "properties": { "domains": { "type": "array", "items": { "$ref": "#/components/schemas/CustomDomainDto" } } } }, "DuplicatePair": { "type": "object", "required": [ "index_a", "index_b", "similarity" ], "properties": { "index_a": { "type": "integer", "format": "int64" }, "index_b": { "type": "integer", "format": "int64" }, "similarity": { "type": "number", "format": "double" } } }, "EdgeResponse": { "type": "object", "required": [ "id", "parent_asset_id", "child_asset_id", "created_at" ], "properties": { "child_asset_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "parent_asset_id": { "type": "string", "format": "uuid" }, "pipeline_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "transformation": { "type": [ "string", "null" ] } } }, "EmailAuthCheckRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" } } }, "EmailAuthDto": { "type": "object", "required": [ "dkim_selectors", "score" ], "properties": { "dkim_selectors": { "type": "array", "items": { "type": "string" } }, "dmarc": { "type": [ "string", "null" ] }, "score": { "type": "integer", "format": "int32", "minimum": 0 }, "spf": { "type": [ "string", "null" ] } } }, "EmitRunLineageRequest": { "type": "object", "description": "Request to emit full lineage for a durable workflow/pipeline run.", "required": [ "template_name" ], "properties": { "output_dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "step_assets": { "type": "array", "items": { "$ref": "#/components/schemas/LineageStepAssetRequest" } }, "template_id": { "type": [ "string", "null" ], "format": "uuid" }, "template_name": { "type": "string" } } }, "EmitRunLineageResponse": { "type": "object", "description": "Response from workflow/pipeline run lineage emission.", "required": [ "run_asset_id", "step_asset_ids" ], "properties": { "dataset_materialization_asset_id": { "type": [ "string", "null" ], "format": "uuid" }, "run_asset_id": { "type": "string", "format": "uuid" }, "step_asset_ids": { "type": "array", "items": { "$ref": "#/components/schemas/LineageStepAssetResponse" } }, "template_asset_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "EnqueueRequest": { "type": "object", "description": "Request to enqueue a new item.", "required": [ "queue_name", "payload" ], "properties": { "delay_secs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "max_retries": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "payload": {}, "priority": { "type": [ "integer", "null" ], "format": "int32" }, "queue_name": { "type": "string" } } }, "EnrichKeywordDto": { "type": "object", "description": "Enriched keyword data returned by the enrichment endpoint.", "required": [ "keyword" ], "properties": { "difficulty": { "type": [ "number", "null" ], "format": "double" }, "keyword": { "type": "string" }, "volume": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "EnrichRequest": { "type": "object", "required": [ "domain" ], "properties": { "context": {}, "domain": { "type": "string" } } }, "EnrichResponse": { "type": "object", "required": [ "domain", "technologies" ], "properties": { "company_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "domain": { "type": "string" }, "employee_count": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "revenue_range": { "type": [ "string", "null" ] }, "technologies": { "type": "array", "items": { "type": "string" } } } }, "EnrichmentSourceResponse": { "type": "object", "description": "Response describing an enrichment source.", "required": [ "name", "description", "capabilities", "required_inputs", "enabled" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "enabled": { "type": "boolean" }, "name": { "type": "string" }, "rate_limit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RateLimitDto" } ] }, "required_inputs": { "type": "array", "items": { "type": "string" } } } }, "EnrichmentStatusResponse": { "type": "object", "description": "Enrichment job status.", "required": [ "job_id", "dataset_id", "source_name", "status", "rows_total", "rows_completed", "rows_failed", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "dataset_id": { "type": "string", "format": "uuid" }, "error": { "type": [ "string", "null" ] }, "job_id": { "type": "string", "format": "uuid" }, "rows_completed": { "type": "integer", "minimum": 0 }, "rows_failed": { "type": "integer", "minimum": 0 }, "rows_total": { "type": "integer", "minimum": 0 }, "source_name": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ErrorAggResponse": { "type": "object", "required": [ "error_type", "count", "last_seen" ], "properties": { "count": { "type": "integer", "format": "int64" }, "error_type": { "type": "string" }, "last_seen": { "type": "string", "format": "date-time" }, "sample_trace_id": { "type": [ "string", "null" ] } } }, "ErrorResponse": { "type": "object", "description": "Documented error response schema for OpenAPI spec.", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "description": "Error code (e.g., \"unauthorized\", \"not_found\")" }, "message": { "type": "string", "description": "Human-readable error message" } } }, "EventCountDto": { "type": "object", "required": [ "event_type", "count" ], "properties": { "count": { "type": "integer", "format": "int64" }, "event_type": { "type": "string" } } }, "EventResponse": { "type": "object", "required": [ "id", "event_type", "properties", "context", "timestamp" ], "properties": { "context": {}, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "properties": {}, "session_id": { "type": [ "string", "null" ] }, "timestamp": { "type": "string", "format": "date-time" }, "trace_id": { "type": [ "string", "null" ] }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "visitor_id": { "type": [ "string", "null" ] } } }, "EvidenceDto": { "type": "object", "required": [ "evidence_type", "description" ], "properties": { "data": {}, "description": { "type": "string" }, "evidence_type": { "type": "string" } } }, "ExecuteEtlStepRequest": { "type": "object", "description": "Request from Restate workflow to execute a single ETL step", "required": [ "run_id", "step_index", "step_name", "operation" ], "properties": { "operation": {}, "parameters": {}, "run_id": { "type": "string", "format": "uuid" }, "step_index": { "type": "integer", "format": "int32" }, "step_name": { "type": "string" } } }, "ExecuteEtlStepResponse": { "type": "object", "description": "Response from ETL step execution", "required": [ "success", "bytes_input", "bytes_output", "rows_processed" ], "properties": { "bytes_input": { "type": "integer", "format": "int64", "minimum": 0 }, "bytes_output": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "output_path": { "type": [ "string", "null" ] }, "rows_processed": { "type": "integer", "format": "int64", "minimum": 0 }, "success": { "type": "boolean" } } }, "ExecuteQueryRequest": { "type": "object", "required": [ "sql" ], "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "sql": { "type": "string" } } }, "ExecuteStepRequest": { "type": "object", "description": "Request to execute a single pipeline step.", "required": [ "run_id", "step" ], "properties": { "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "include_rows": { "type": "boolean", "description": "Include output rows in the response so a durable workflow can pass\nthem to downstream steps. Keep false for callers that only need counts." }, "output_dataset_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional dataset to replace with this step's output rows. Durable\nworkflows set this only on their final step to materialize results." }, "parameters": {}, "rows": { "type": "array", "items": { "type": "object" }, "description": "Optional in-memory input rows for workflow-template execution. When\nomitted, the endpoint falls back to loading rows from dataset_id." }, "run_id": { "type": "string", "format": "uuid" }, "step": { "$ref": "#/components/schemas/PipelineStepDto" } } }, "ExecuteStepResponse": { "type": "object", "description": "Response from executing a single pipeline step.", "required": [ "success", "rows_input", "rows_output" ], "properties": { "error": { "type": [ "string", "null" ] }, "rows": { "type": "array", "items": { "type": "object" } }, "rows_input": { "type": "integer", "minimum": 0 }, "rows_output": { "type": "integer", "minimum": 0 }, "success": { "type": "boolean" } } }, "ExperimentResponse": { "type": "object", "required": [ "id", "action_type", "status", "target_urls", "baseline_value", "observations_count", "started_at" ], "properties": { "action_type": { "type": "string" }, "baseline_value": { "type": "number", "format": "double" }, "concluded_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "observations_count": { "type": "integer", "format": "int64" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "target_urls": { "type": "array", "items": { "type": "string" } } } }, "ExplainRequest": { "type": "object", "required": [ "score_id" ], "properties": { "score_id": { "type": "string", "format": "uuid" } } }, "ExplainResponse": { "type": "object", "required": [ "explanations" ], "properties": { "explanations": { "type": "array", "items": { "$ref": "#/components/schemas/ExplanationDto" } } } }, "ExplanationDto": { "type": "object", "required": [ "dimension", "score", "weight", "signal_names", "reasoning" ], "properties": { "dimension": { "type": "string" }, "reasoning": { "type": "string" }, "score": { "type": "number", "format": "double" }, "signal_names": { "type": "array", "items": { "type": "string" } }, "weight": { "type": "number", "format": "double" } } }, "ExportDatasetRequest": { "type": "object", "description": "Request to export a dataset.", "properties": { "columns": { "type": [ "array", "null" ], "items": { "type": "string" } }, "destination": { "type": "string", "description": "Export destination: \"inline\" (default) or \"object_store\"" }, "format": { "type": "string" } } }, "ExportDatasetResponse": { "type": "object", "description": "Response for dataset export.", "required": [ "format", "row_count" ], "properties": { "data": {}, "format": { "type": "string" }, "path": { "type": [ "string", "null" ], "description": "Object store path (when destination = \"object_store\")" }, "row_count": { "type": "integer", "minimum": 0 }, "size_bytes": { "type": [ "integer", "null" ], "format": "int64", "description": "File size in bytes (when destination = \"object_store\")", "minimum": 0 }, "url": { "type": [ "string", "null" ], "description": "Presigned URL (when destination = \"object_store\")" } } }, "ExportQueryRequest": { "type": "object", "description": "Request to export query results to object store", "required": [ "sql", "output_path", "format" ], "properties": { "format": { "type": "string" }, "output_path": { "type": "string" }, "sql": { "type": "string" } } }, "ExportQueryResponse": { "type": "object", "description": "Response from query export", "required": [ "output_path", "row_count", "bytes_written" ], "properties": { "bytes_written": { "type": "integer", "format": "int64", "minimum": 0 }, "output_path": { "type": "string" }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ExportSpiderResponse": { "type": "object", "description": "Spider export response (the full definition).", "required": [ "definition", "exported_at" ], "properties": { "definition": {}, "exported_at": { "type": "string", "format": "date-time" } } }, "ExtractionMetadata": { "type": "object", "required": [ "extractor_used", "content_hash" ], "properties": { "content_hash": { "type": "string" }, "extractor_used": { "type": "string" } } }, "ExtractionOptions": { "type": "object", "properties": { "extract_keywords": { "type": [ "boolean", "null" ] }, "include_images": { "type": [ "boolean", "null" ] }, "include_metadata": { "type": [ "boolean", "null" ] }, "render_mode": { "type": [ "string", "null" ], "description": "Render policy: `\"static\" | \"auto\" | \"js\"`. Defaults to `\"auto\"`\n(static first, JS-render only when the static extraction looks thin)." }, "summarize": { "type": [ "boolean", "null" ] } } }, "FeedbackLoopDto": { "type": "object", "required": [ "id", "url", "loop_type", "issue_category", "status", "detected_at", "verification_results" ], "properties": { "detected_at": { "type": "string", "format": "date-time" }, "diagnosed_at": { "type": [ "string", "null" ], "format": "date-time" }, "diagnosis": { "type": [ "string", "null" ] }, "escalated_at": { "type": [ "string", "null" ], "format": "date-time" }, "fix_applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "fix_description": { "type": [ "string", "null" ] }, "fix_suggested_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "issue_category": { "type": "string" }, "loop_type": { "type": "string" }, "outcome": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "url": { "type": "string" }, "verification_results": {} } }, "FeedbackStatsResponse": { "type": "object", "required": [ "total_loops", "resolved", "regressed", "escalated", "pending_verification", "success_rate" ], "properties": { "avg_resolution_days": { "type": [ "number", "null" ], "format": "double" }, "escalated": { "type": "integer", "format": "int64" }, "pending_verification": { "type": "integer", "format": "int64" }, "regressed": { "type": "integer", "format": "int64" }, "resolved": { "type": "integer", "format": "int64" }, "success_rate": { "type": "number", "format": "double" }, "total_loops": { "type": "integer", "format": "int64" } } }, "FetchRequest": { "type": "object", "description": "Request to fetch a remote artifact", "required": [ "url", "output_path" ], "properties": { "headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "max_size_bytes": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "output_path": { "type": "string" }, "url": { "type": "string" } } }, "FetchResponse": { "type": "object", "description": "Response from fetch operation", "required": [ "output_path", "bytes_downloaded" ], "properties": { "bytes_downloaded": { "type": "integer", "format": "int64", "minimum": 0 }, "output_path": { "type": "string" } } }, "FieldHealthDto": { "type": "object", "description": "Individual field health.", "required": [ "field_name", "completeness", "status" ], "properties": { "completeness": { "type": "number", "format": "double" }, "field_name": { "type": "string" }, "status": { "type": "string" } } }, "FileChangeDto": { "type": "object", "required": [ "path", "action" ], "properties": { "action": { "type": "string" }, "explanation": { "type": [ "string", "null" ] }, "find": { "type": [ "string", "null" ] }, "path": { "type": "string" }, "replace": { "type": [ "string", "null" ] } } }, "FilterRequest": { "type": "object", "required": [ "dataset_id", "rules" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "rules": {} } }, "FilterResponse": { "type": "object", "required": [ "dataset_id", "total_rows", "passed_rows", "failed_rows", "results" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "failed_rows": { "type": "integer", "format": "int64" }, "passed_rows": { "type": "integer", "format": "int64" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/FilterResultItem" } }, "total_rows": { "type": "integer", "format": "int64" } } }, "FilterResultItem": { "type": "object", "required": [ "row_index", "passed" ], "properties": { "passed": { "type": "boolean" }, "reason": { "type": [ "string", "null" ] }, "row_index": { "type": "integer", "format": "int64" } } }, "FindSelectorsRequest": { "type": "object", "description": "Request to find CSS selectors matching content on a page.", "required": [ "url", "target_text" ], "properties": { "max_results": { "type": [ "integer", "null" ], "minimum": 0 }, "target_text": { "type": "string" }, "url": { "type": "string" } } }, "FindSelectorsResponse": { "type": "object", "description": "Response with discovered selectors.", "required": [ "url", "target_text", "selectors" ], "properties": { "selectors": { "type": "array", "items": { "$ref": "#/components/schemas/SelectorMatchDto" } }, "target_text": { "type": "string" }, "url": { "type": "string" } } }, "ForecastPointDto": { "type": "object", "required": [ "month", "mrr_p50", "mrr_lower", "mrr_upper" ], "properties": { "month": { "type": "integer", "format": "int32", "minimum": 0 }, "mrr_lower": { "type": "number", "format": "double" }, "mrr_p50": { "type": "number", "format": "double" }, "mrr_upper": { "type": "number", "format": "double" } } }, "ForecastRequest": { "type": "object", "description": "Revenue forecast request with SEO assumptions.", "required": [ "current_mrr_cents", "monthly_churn", "monthly_new_customers", "arpc_cents" ], "properties": { "arpc_cents": { "type": "integer", "format": "int64" }, "current_mrr_cents": { "type": "integer", "format": "int64" }, "horizon_months": { "type": "integer", "format": "int32", "minimum": 0 }, "monthly_churn": { "type": "number", "format": "double" }, "monthly_new_customers": { "type": "number", "format": "double" }, "seo_conversion_rate": { "type": [ "number", "null" ], "format": "double" }, "seo_traffic_increase_pct": { "type": [ "number", "null" ], "format": "double" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "ForecastResponse": { "type": "object", "required": [ "pipeline_value_cents", "weighted_value_cents", "expected_close_30d_cents", "expected_close_90d_cents" ], "properties": { "expected_close_30d_cents": { "type": "integer", "format": "int64" }, "expected_close_90d_cents": { "type": "integer", "format": "int64" }, "pipeline_value_cents": { "type": "integer", "format": "int64" }, "weighted_value_cents": { "type": "integer", "format": "int64" } } }, "FrontierStatsResponse": { "type": "object", "description": "Frontier statistics for a crawl job.", "required": [ "job_id", "total_urls", "pending", "in_flight", "completed", "failed", "skipped" ], "properties": { "completed": { "type": "integer", "format": "int32", "minimum": 0 }, "failed": { "type": "integer", "format": "int32", "minimum": 0 }, "in_flight": { "type": "integer", "format": "int32", "minimum": 0 }, "job_id": { "type": "string", "format": "uuid" }, "pending": { "type": "integer", "format": "int32", "minimum": 0 }, "skipped": { "type": "integer", "format": "int32", "minimum": 0 }, "total_urls": { "type": "integer", "format": "int32", "minimum": 0 } } }, "FunnelRequest": { "type": "object", "required": [ "project_id", "steps" ], "properties": { "from": { "type": [ "string", "null" ], "format": "date-time" }, "project_id": { "type": "string", "format": "uuid" }, "steps": { "type": "array", "items": { "type": "string" } }, "to": { "type": [ "string", "null" ], "format": "date-time" } } }, "FunnelResponse": { "type": "object", "required": [ "steps" ], "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/FunnelStepDto" } } } }, "FunnelStepDto": { "type": "object", "required": [ "event_type", "count", "conversion_rate" ], "properties": { "conversion_rate": { "type": "number", "format": "double" }, "count": { "type": "integer", "format": "int64" }, "event_type": { "type": "string" } } }, "GateRequest": { "type": "object", "description": "Request to run a structured quality gate on dataset rows.", "required": [ "dataset_id", "policy" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "policy": { "description": "Policy rules that operate on structured JSON row data." }, "quarantine": { "type": "boolean", "description": "If true, quarantine failing rows (set enrichment_status.quarantined = true). Default false." } } }, "GateResponse": { "type": "object", "required": [ "dataset_id", "total_rows", "passed_rows", "failed_rows", "passed", "quarantined" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "failed_rows": { "type": "integer", "format": "int64" }, "passed": { "type": "array", "items": { "$ref": "#/components/schemas/GateRowResult" } }, "passed_rows": { "type": "integer", "format": "int64" }, "quarantined": { "type": "array", "items": { "$ref": "#/components/schemas/GateRowResult" } }, "total_rows": { "type": "integer", "format": "int64" } } }, "GateRowResult": { "type": "object", "required": [ "row_index", "passed", "violations", "data" ], "properties": { "data": { "description": "The actual row data for inspection" }, "passed": { "type": "boolean" }, "row_id": { "type": [ "string", "null" ], "format": "uuid" }, "row_index": { "type": "integer", "format": "int64" }, "violations": { "type": "array", "items": { "$ref": "#/components/schemas/GateViolationDto" } } } }, "GateViolationDto": { "type": "object", "required": [ "rule_type", "field", "reason" ], "properties": { "field": { "type": "string" }, "reason": { "type": "string" }, "rule_type": { "type": "string" } } }, "GenerateKeyRequest": { "type": "object", "description": "Request to generate a new IndexNow key", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "format": "uuid" } } }, "GenerateKeyResponse": { "type": "object", "description": "Response with generated key details", "required": [ "key", "key_file_url", "key_file_content" ], "properties": { "key": { "type": "string" }, "key_file_content": { "type": "string" }, "key_file_url": { "type": "string" } } }, "GenerateProfileRequest": { "type": "object", "required": [ "site_id", "url" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" } } }, "GenerateRequest": { "type": "object", "required": [ "operation", "model_endpoint" ], "properties": { "config": {}, "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "input_rows": { "type": [ "integer", "null" ], "format": "int64" }, "model_endpoint": {}, "operation": { "type": "string" } } }, "GeoLocationDto": { "type": "object", "required": [ "country" ], "properties": { "city": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "region": { "type": [ "string", "null" ] } } }, "GeoRefItem": { "type": "object", "required": [ "zip" ], "properties": { "cbsa_code": { "type": [ "string", "null" ] }, "cbsa_name": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "medicare_locality": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "zip": { "type": "string" } } }, "GraphImpactRequest": { "type": "object", "description": "Request for graph impact analysis.", "required": [ "node_id" ], "properties": { "node_id": { "type": "string", "format": "uuid", "description": "Node ID to analyze impact from." } } }, "GraphImpactResponse": { "type": "object", "description": "Response from graph impact analysis.", "required": [ "node_id", "impacted_nodes" ], "properties": { "impacted_nodes": { "type": "array", "items": { "$ref": "#/components/schemas/ImpactedNodeDto" } }, "node_id": { "type": "string", "format": "uuid" } } }, "GraphNodeResponse": { "type": "object", "required": [ "asset", "parents", "children" ], "properties": { "asset": { "$ref": "#/components/schemas/AssetResponse" }, "children": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "parents": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "GraphPropagateRequest": { "type": "object", "description": "Request for signal propagation simulation.", "required": [ "source_node", "signal_type", "severity" ], "properties": { "severity": { "type": "number", "format": "double", "description": "Signal severity (0.0 - 1.0)." }, "signal_type": { "type": "string", "description": "Signal type: \"quality_drop\", \"schema_drift\", \"cost_spike\", \"score_change\"." }, "source_node": { "type": "string", "format": "uuid", "description": "Source node ID for the signal." } } }, "GraphPropagateResponse": { "type": "object", "description": "Response from signal propagation.", "required": [ "source_node", "affected_nodes" ], "properties": { "affected_nodes": { "type": "array", "items": { "$ref": "#/components/schemas/AffectedNodeDto" } }, "source_node": { "type": "string", "format": "uuid" } } }, "GraphResponse": { "type": "object", "required": [ "nodes", "roots" ], "properties": { "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/GraphNodeResponse" } }, "roots": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "GraphRootCauseRequest": { "type": "object", "description": "Request for root cause tracing.", "required": [ "anomaly_node_id" ], "properties": { "anomaly_node_id": { "type": "string", "format": "uuid", "description": "Anomaly node ID to trace back from." } } }, "GraphRootCauseResponse": { "type": "object", "description": "Response from root cause tracing.", "required": [ "anomaly_node_id", "causal_chains" ], "properties": { "anomaly_node_id": { "type": "string", "format": "uuid" }, "causal_chains": { "type": "array", "items": { "$ref": "#/components/schemas/CausalChainDto" } } } }, "GscIssueDto": { "type": "object", "required": [ "category", "severity", "description", "affected_urls" ], "properties": { "affected_urls": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "description": { "type": "string" }, "root_cause": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GscRootCauseDto" } ] }, "severity": { "type": "string" } } }, "GscRootCauseDto": { "type": "object", "required": [ "category", "explanation", "confidence" ], "properties": { "category": { "type": "string" }, "confidence": { "type": "number", "format": "float" }, "explanation": { "type": "string" } } }, "GscSnapshotResponse": { "type": "object", "required": [ "property_url", "total_clicks_7d", "total_impressions_7d", "avg_position_7d", "avg_ctr_7d", "sitemap_count" ], "properties": { "avg_ctr_7d": { "type": "number", "format": "double" }, "avg_position_7d": { "type": "number", "format": "double" }, "property_url": { "type": "string" }, "sitemap_count": { "type": "integer", "minimum": 0 }, "total_clicks_7d": { "type": "number", "format": "double" }, "total_impressions_7d": { "type": "number", "format": "double" } } }, "GuardrailResponse": { "type": "object", "required": [ "dataset_id", "violations", "passed" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "passed": { "type": "boolean" }, "violations": { "type": "array", "items": {} } } }, "HeadingDto": { "type": "object", "description": "A heading element.", "required": [ "level", "text" ], "properties": { "level": { "type": "integer", "format": "int32", "minimum": 0 }, "text": { "type": "string" } } }, "HospitalItem": { "type": "object", "required": [ "hospital_name", "state" ], "properties": { "address_line1": { "type": [ "string", "null" ] }, "cbsa_code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "cms_certification_number": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "emergency_services": { "type": [ "boolean", "null" ] }, "hospital_name": { "type": "string" }, "hospital_type": { "type": [ "string", "null" ] }, "npi": { "type": [ "string", "null" ] }, "ownership_type": { "type": [ "string", "null" ] }, "state": { "type": "string" }, "zip": { "type": [ "string", "null" ] } } }, "HybridQueryRequest": { "type": "object", "description": "Request for a hybrid DuckDB query", "required": [ "sql" ], "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "sql": { "type": "string" } } }, "HybridQueryResponse": { "type": "object", "description": "Response from a hybrid query", "required": [ "columns", "rows", "row_count" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnInfo" } }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "rows": { "type": "array", "items": {} } } }, "IdentifyRequest": { "type": "object", "required": [ "visitor_id", "user_id" ], "properties": { "traits": {}, "user_id": { "type": "string", "format": "uuid" }, "visitor_id": { "type": "string" } } }, "ImageSummaryDto": { "type": "object", "description": "Summary of images found in HTML.", "required": [ "total", "missing_alt", "lazy_loaded" ], "properties": { "lazy_loaded": { "type": "integer", "minimum": 0 }, "missing_alt": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 } } }, "ImpactedNodeDto": { "type": "object", "required": [ "node_id", "node_label", "node_type", "distance", "impact_severity", "path" ], "properties": { "distance": { "type": "integer", "minimum": 0 }, "impact_severity": { "type": "number", "format": "double" }, "node_id": { "type": "string", "format": "uuid" }, "node_label": { "type": "string" }, "node_type": { "type": "string" }, "path": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "ImportCsvRequest": { "type": "object", "required": [ "site_id", "keywords" ], "properties": { "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/CsvKeywordRow" } }, "site_id": { "type": "string", "format": "uuid" } } }, "ImportDatasetRequest": { "type": "object", "description": "Request to import data into a dataset.", "required": [ "format", "data" ], "properties": { "data": {}, "format": { "type": "string" }, "upsert": { "type": "boolean" } } }, "ImportGscRequest": { "type": "object", "required": [ "site_id", "start_date", "end_date" ], "properties": { "end_date": { "type": "string" }, "limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "min_impressions": { "type": [ "number", "null" ], "format": "double" }, "site_id": { "type": "string", "format": "uuid" }, "start_date": { "type": "string" } } }, "ImportResponse": { "type": "object", "required": [ "imported", "skipped" ], "properties": { "imported": { "type": "integer", "minimum": 0 }, "skipped": { "type": "integer", "minimum": 0 } } }, "ImportSpiderRequest": { "type": "object", "description": "Request to import a spider definition from JSON.", "required": [ "definition" ], "properties": { "definition": {}, "name_override": { "type": [ "string", "null" ] } } }, "IncidentEventResponse": { "type": "object", "description": "Incident event (timeline entry) response DTO.", "required": [ "id", "incident_id", "event_type", "description", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "description": { "type": "string" }, "event_type": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "incident_id": { "type": "string", "format": "uuid" } } }, "IncidentResponse": { "type": "object", "description": "Incident response DTO.", "required": [ "id", "account_id", "incident_type", "source_id", "source_type", "severity", "status", "created_at", "updated_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "detected_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "incident_type": { "type": "string" }, "postmortem_url": { "type": [ "string", "null" ] }, "remediation": { "type": [ "string", "null" ] }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "root_cause": { "type": [ "string", "null" ] }, "severity": { "type": "string" }, "source_id": { "type": "string" }, "source_type": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "IndexNowResultDto": { "type": "object", "description": "Individual URL submission result", "required": [ "url", "success" ], "properties": { "error": { "type": [ "string", "null" ] }, "success": { "type": "boolean" }, "url": { "type": "string" } } }, "IndexNowSubmitRequest": { "type": "object", "description": "Request to submit URLs via IndexNow protocol", "required": [ "site_id", "urls" ], "properties": { "key": { "type": [ "string", "null" ], "description": "IndexNow key (uses stored key if omitted)" }, "site_id": { "type": "string", "format": "uuid" }, "urls": { "type": "array", "items": { "type": "string" }, "description": "URLs to submit (absolute or relative paths)" } } }, "IndexNowSubmitResponse": { "type": "object", "description": "Response from IndexNow URL submission", "required": [ "total_urls", "success_count", "failure_count", "results" ], "properties": { "failure_count": { "type": "integer", "minimum": 0 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/IndexNowResultDto" } }, "success_count": { "type": "integer", "minimum": 0 }, "total_urls": { "type": "integer", "minimum": 0 } } }, "IndexRequest": { "type": "object", "required": [ "site_id", "url" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" } } }, "IndexResponse": { "type": "object", "required": [ "submitted", "url" ], "properties": { "submitted": { "type": "boolean" }, "url": { "type": "string" } } }, "IngestEvent": { "type": "object", "required": [ "event_type" ], "properties": { "context": {}, "event_type": { "type": "string" }, "properties": {}, "session_id": { "type": [ "string", "null" ] }, "timestamp": { "type": [ "string", "null" ], "format": "date-time" }, "trace_id": { "type": [ "string", "null" ] }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "visitor_id": { "type": [ "string", "null" ] } } }, "IngestEventsRequest": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/IngestEvent" } } } }, "IngestEventsResponse": { "type": "object", "required": [ "accepted", "rejected", "errors" ], "properties": { "accepted": { "type": "integer", "minimum": 0 }, "errors": { "type": "array", "items": { "type": "string" } }, "rejected": { "type": "integer", "minimum": 0 } } }, "InsightDto": { "type": "object", "required": [ "category", "title", "description", "confidence" ], "properties": { "category": { "type": "string" }, "confidence": { "type": "number", "format": "double" }, "description": { "type": "string" }, "recommended_action": { "type": [ "string", "null" ] }, "title": { "type": "string" } } }, "InsightsResponse": { "type": "object", "required": [ "insights", "generated_at" ], "properties": { "generated_at": { "type": "string", "format": "date-time" }, "insights": { "type": "array", "items": { "$ref": "#/components/schemas/InsightDto" } } } }, "InspectRequest": { "type": "object", "required": [ "site_id", "url" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" } } }, "InspectUrlRequest": { "type": "object", "description": "Request to inspect a URL.", "required": [ "url" ], "properties": { "extract_selectors": { "type": "boolean" }, "js_rendering": { "type": "boolean" }, "url": { "type": "string" } } }, "InspectUrlResponse": { "type": "object", "description": "Response for URL inspection.", "required": [ "url", "status_code", "content_type", "word_count", "internal_links", "external_links", "images", "structured_data", "response_time_ms", "headers" ], "properties": { "canonical": { "type": [ "string", "null" ] }, "content_type": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "external_links": { "type": "integer", "minimum": 0 }, "h1": { "type": [ "string", "null" ] }, "headers": {}, "images": { "type": "integer", "minimum": 0 }, "internal_links": { "type": "integer", "minimum": 0 }, "response_time_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "status_code": { "type": "integer", "format": "int32", "minimum": 0 }, "structured_data": { "type": "array", "items": { "type": "string" } }, "title": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "word_count": { "type": "integer", "minimum": 0 } } }, "InspectionAnalysisResponse": { "type": "object", "required": [ "inspection", "issues", "issue_count" ], "properties": { "inspection": { "type": "object", "description": "Full URL inspection result from Google Search Console" }, "issue_count": { "type": "integer", "minimum": 0 }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/GscIssueDto" } } } }, "IssueDto": { "type": "object", "required": [ "category", "severity", "description", "affected_urls" ], "properties": { "affected_urls": { "type": "array", "items": { "type": "string" } }, "category": { "type": "string" }, "description": { "type": "string" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/EvidenceDto" } }, "remediation": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RemediationDto" } ] }, "root_cause": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RootCauseDto" } ] }, "severity": { "type": "string" } } }, "IssueSeverityDistribution": { "type": "object", "required": [ "critical", "high", "medium", "low", "info" ], "properties": { "critical": { "type": "integer", "format": "int64" }, "high": { "type": "integer", "format": "int64" }, "info": { "type": "integer", "format": "int64" }, "low": { "type": "integer", "format": "int64" }, "medium": { "type": "integer", "format": "int64" } } }, "JobActionResponse": { "type": "object", "description": "Response for a job lifecycle action (pause, resume, cancel).", "required": [ "job_id", "action", "previous_status", "new_status" ], "properties": { "action": { "type": "string" }, "job_id": { "type": "string", "format": "uuid" }, "new_status": { "type": "string" }, "previous_status": { "type": "string" } } }, "JobListResponse": { "type": "object", "description": "List of crawl jobs.", "required": [ "jobs", "total" ], "properties": { "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/JobResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "JobResponse": { "type": "object", "description": "Response for a crawl job.", "required": [ "id", "site_id", "status", "budget", "progress", "recrawl_policy", "created_at", "updated_at" ], "properties": { "budget": { "$ref": "#/components/schemas/CrawlBudgetDto" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "progress": { "$ref": "#/components/schemas/CrawlProgressDto" }, "recrawl_policy": { "$ref": "#/components/schemas/RecrawlPolicyDto" }, "site_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "stealth_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StealthConfigDto" } ] }, "strategy_config": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StrategyConfigDto" } ] }, "strategy_id": { "type": [ "string", "null" ], "format": "uuid" }, "updated_at": { "type": "string", "format": "date-time" } } }, "KeywordContextDto": { "type": "object", "description": "Keyword targeting intelligence for a page.", "required": [ "target_keyword", "recommendation" ], "properties": { "current_position": { "type": [ "number", "null" ], "format": "double", "description": "Current average SERP position (from GSC or keyword tracker)" }, "monthly_volume": { "type": [ "integer", "null" ], "format": "int32", "description": "Monthly search volume" }, "recommendation": { "type": "string", "description": "Action recommendation based on current position" }, "target_keyword": { "type": "string", "description": "The keyword this page appears to target" } } }, "KeywordDto": { "type": "object", "required": [ "id", "query", "source", "tags", "created_at" ], "properties": { "avg_position": { "type": [ "number", "null" ], "format": "double" }, "clicks_30d": { "type": [ "number", "null" ], "format": "double" }, "created_at": { "type": "string", "format": "date-time" }, "ctr": { "type": [ "number", "null" ], "format": "double" }, "difficulty": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": "string", "format": "uuid" }, "impressions_30d": { "type": [ "number", "null" ], "format": "double" }, "priority": { "type": [ "string", "null" ] }, "query": { "type": "string" }, "search_volume": { "type": [ "integer", "null" ], "format": "int32" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "KeywordRecommendation": { "type": "object", "required": [ "query", "reason" ], "properties": { "estimated_difficulty": { "type": [ "integer", "null" ], "format": "int32" }, "query": { "type": "string" }, "reason": { "type": "string" } } }, "KeywordUpdate": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" }, "priority": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "KnowledgeGraphResponse": { "type": "object", "required": [ "results", "query" ], "properties": { "query": { "type": "string" }, "results": { "type": "array", "items": {} } } }, "KnowledgeQueryParams": { "type": "object", "required": [ "q" ], "properties": { "q": { "type": "string" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "LandscapeResponse": { "type": "object", "required": [ "site_id", "competitors", "overlap_keywords", "unique_keywords" ], "properties": { "avg_position_ours": { "type": [ "number", "null" ], "format": "double", "description": "Average position across our shared keywords" }, "avg_position_theirs": { "type": [ "number", "null" ], "format": "double", "description": "Average position across competitor shared keywords" }, "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorDto" } }, "content_gaps": { "type": "array", "items": { "$ref": "#/components/schemas/ContentGap" }, "description": "Keywords where >=2 competitors rank top-10 and we don't" }, "message": { "type": [ "string", "null" ], "description": "Message when SeoDataProvider is unavailable" }, "overlap_keywords": { "type": "integer", "minimum": 0 }, "overlap_score": { "type": [ "number", "null" ], "format": "double", "description": "Jaccard index: shared_keywords / union_keywords (0.0-1.0)" }, "shared_keywords": { "type": "array", "items": { "$ref": "#/components/schemas/SharedKeyword" }, "description": "Keywords shared with competitors, including positions for both sides" }, "site_id": { "type": "string", "format": "uuid" }, "unique_keywords": { "type": "integer", "minimum": 0 } } }, "LatestAuditSummary": { "type": "object", "required": [ "audit_id", "status" ], "properties": { "audit_id": { "type": "string", "format": "uuid" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "issues_found": { "type": [ "integer", "null" ], "format": "int32" }, "pages_crawled": { "type": [ "integer", "null" ], "format": "int32" }, "score": { "type": [ "integer", "null" ], "format": "int32" }, "status": { "type": "string" } } }, "LeadResponse": { "type": "object", "required": [ "id", "source", "tier", "status", "enrichment_data", "created_at", "updated_at" ], "properties": { "company_name": { "type": [ "string", "null" ] }, "composite_score": { "type": [ "number", "null" ], "format": "double" }, "contact_email": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": [ "string", "null" ] }, "enrichment_data": {}, "fit_score": { "type": [ "number", "null" ], "format": "double" }, "id": { "type": "string", "format": "uuid" }, "intent_score": { "type": [ "number", "null" ], "format": "double" }, "source": { "type": "string" }, "status": { "type": "string" }, "tier": { "type": "string" }, "timing_score": { "type": [ "number", "null" ], "format": "double" }, "updated_at": { "type": "string", "format": "date-time" } } }, "LineageStepAssetRequest": { "type": "object", "description": "A workflow/pipeline step output to register in the control-plane lineage graph.", "required": [ "step_index", "step_name", "operation", "rows_output" ], "properties": { "operation": { "type": "string" }, "rows_output": { "type": "integer", "minimum": 0 }, "step_index": { "type": "integer", "format": "int32" }, "step_name": { "type": "string" } } }, "LineageStepAssetResponse": { "type": "object", "description": "Step asset registered by a lineage emission request.", "required": [ "step_name", "asset_id" ], "properties": { "asset_id": { "type": "string", "format": "uuid" }, "step_name": { "type": "string" } } }, "LinkGraphMetricsDto": { "type": "object", "description": "Graph-level link health metrics aligned with DSOF §3.2", "required": [ "total_pages", "orphan_count", "avg_links_per_page", "max_click_depth", "gini_coefficient", "anchor_diversity" ], "properties": { "anchor_diversity": { "type": "number", "format": "double", "description": "Shannon entropy of anchor text diversity (target: >0.7)" }, "avg_links_per_page": { "type": "number", "format": "double" }, "gini_coefficient": { "type": "number", "format": "double", "description": "Gini coefficient of inbound link distribution (target: <0.6)" }, "max_click_depth": { "type": "integer", "minimum": 0 }, "orphan_count": { "type": "integer", "minimum": 0 }, "total_pages": { "type": "integer", "minimum": 0 } } }, "LinkHealthDto": { "type": "object", "description": "Compact link health summary for coaching context", "required": [ "orphan_pages", "avg_links_per_page", "max_depth", "targets_met" ], "properties": { "avg_links_per_page": { "type": "number", "format": "double" }, "max_depth": { "type": "integer", "minimum": 0 }, "orphan_pages": { "type": "integer", "minimum": 0 }, "targets_met": { "$ref": "#/components/schemas/LinkTargets", "description": "Quick pass/fail flags against DSOF/GEO framework targets" } } }, "LinkSuggestionCoachingDto": { "type": "object", "description": "Compact link suggestion for coaching context", "required": [ "source_url", "target_url", "anchor_text", "reason" ], "properties": { "anchor_text": { "type": "string" }, "reason": { "type": "string" }, "source_url": { "type": "string" }, "target_url": { "type": "string" } } }, "LinkSuggestionDto": { "type": "object", "required": [ "source_url", "target_url", "anchor_text", "reason", "priority" ], "properties": { "anchor_text": { "type": "string" }, "priority": { "type": "number", "format": "double" }, "reason": { "type": "string" }, "source_url": { "type": "string" }, "target_url": { "type": "string" } } }, "LinkSummaryDto": { "type": "object", "description": "Summary of links found in HTML.", "required": [ "internal", "external", "anchors", "nofollow" ], "properties": { "anchors": { "type": "integer", "minimum": 0 }, "external": { "type": "integer", "minimum": 0 }, "internal": { "type": "integer", "minimum": 0 }, "nofollow": { "type": "integer", "minimum": 0 } } }, "LinkTargets": { "type": "object", "description": "Pass/fail checks against DSOF §3.2 and GEO §6.3 targets", "required": [ "orphans_zero", "depth_within_limit", "links_per_page_ok", "equity_distributed" ], "properties": { "depth_within_limit": { "type": "boolean", "description": "DSOF §3.2: max click depth ≤4, GEO §5.3: ≤3 clicks" }, "equity_distributed": { "type": "boolean", "description": "DSOF §3.2: Gini coefficient <0.6 (link equity well-distributed)" }, "links_per_page_ok": { "type": "boolean", "description": "DSOF §3.2: average ≥5 internal links per page" }, "orphans_zero": { "type": "boolean", "description": "DSOF §3.2: 0 orphan pages" } } }, "LinksRequest": { "type": "object", "required": [ "site_id", "url" ], "properties": { "site_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" } } }, "LinksResponse": { "type": "object", "required": [ "suggestions" ], "properties": { "graph_metrics": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LinkGraphMetricsDto", "description": "Graph-level health metrics (DSOF §3.2 aligned)" } ] }, "suggestions": { "type": "array", "items": { "$ref": "#/components/schemas/LinkSuggestionDto" } } } }, "ListDataSourcesResponse": { "type": "object", "required": [ "sources" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/DataSourceDetail" } } } }, "ListKeywordsQuery": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64" }, "offset": { "type": [ "integer", "null" ], "format": "int64" }, "priority": { "type": [ "string", "null" ] }, "site_id": { "type": [ "string", "null" ], "format": "uuid" }, "source": { "type": [ "string", "null" ] } } }, "ListPipelineRunsResponse": { "type": "object", "required": [ "runs" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineRunDetail" } } } }, "ListRunsQuery": { "type": "object", "description": "Query params for listing runs.", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64" }, "offset": { "type": [ "integer", "null" ], "format": "int64" }, "status": { "type": [ "string", "null" ] } } }, "LoadRequest": { "type": "object", "description": "Request to bulk load Parquet into PostgreSQL", "required": [ "parquet_prefix", "table_name", "column_names" ], "properties": { "column_names": { "type": "array", "items": { "type": "string" } }, "parquet_prefix": { "type": "string" }, "table_name": { "type": "string" } } }, "LoadResponse": { "type": "object", "description": "Response from bulk load operation", "required": [ "table_name", "rows_loaded", "partitions_processed" ], "properties": { "partitions_processed": { "type": "integer", "format": "int64", "minimum": 0 }, "rows_loaded": { "type": "integer", "format": "int64", "minimum": 0 }, "table_name": { "type": "string" } } }, "MarketStats": { "type": "object", "required": [ "rate_count" ], "properties": { "mean_rate": { "type": [ "number", "null" ], "format": "double" }, "median_rate": { "type": [ "number", "null" ], "format": "double" }, "p10_rate": { "type": [ "number", "null" ], "format": "double" }, "p90_rate": { "type": [ "number", "null" ], "format": "double" }, "rate_count": { "type": "integer", "format": "int64" } } }, "MeasurementAttributionResponse": { "type": "object", "required": [ "id", "experiment_id", "outcome_delta", "outcome_direction", "confidence", "confounders", "method", "created_at" ], "properties": { "confidence": { "type": "number", "format": "double" }, "confounders": {}, "created_at": { "type": "string", "format": "date-time" }, "experiment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "method": { "type": "string" }, "outcome_delta": { "type": "number", "format": "double" }, "outcome_direction": { "type": "string" } } }, "MeasurementDashboardResponse": { "type": "object", "required": [ "total_experiments", "active", "concluded", "positive_outcomes", "avg_confidence" ], "properties": { "active": { "type": "integer", "format": "int64" }, "avg_confidence": { "type": "number", "format": "double" }, "concluded": { "type": "integer", "format": "int64" }, "positive_outcomes": { "type": "integer", "format": "int64" }, "total_experiments": { "type": "integer", "format": "int64" } } }, "MentionResponse": { "type": "object", "required": [ "id", "linkedin_id", "kind", "monitor_id", "reactions_like", "reactions_celebrate", "reactions_support", "reactions_love", "reactions_insightful", "reactions_funny", "reactions_total", "comment_count", "share_count", "discovered_at", "matched_keywords" ], "properties": { "author_company": { "type": [ "string", "null" ] }, "author_follower_count": { "type": [ "integer", "null" ], "format": "int32" }, "author_headline": { "type": [ "string", "null" ] }, "author_industry": { "type": [ "string", "null" ] }, "author_location": { "type": [ "string", "null" ] }, "author_name": { "type": [ "string", "null" ] }, "author_profile_url": { "type": [ "string", "null" ] }, "author_seniority": { "type": [ "string", "null" ] }, "comment_count": { "type": "integer", "format": "int32" }, "content": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "discovered_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "linkedin_id": { "type": "string" }, "matched_keywords": { "type": "array", "items": { "type": "string" } }, "monitor_id": { "type": "string", "format": "uuid" }, "permalink": { "type": [ "string", "null" ] }, "reactions_celebrate": { "type": "integer", "format": "int32" }, "reactions_funny": { "type": "integer", "format": "int32" }, "reactions_insightful": { "type": "integer", "format": "int32" }, "reactions_like": { "type": "integer", "format": "int32" }, "reactions_love": { "type": "integer", "format": "int32" }, "reactions_support": { "type": "integer", "format": "int32" }, "reactions_total": { "type": "integer", "format": "int32" }, "sentiment": { "type": [ "string", "null" ] }, "share_count": { "type": "integer", "format": "int32" }, "signal_score": { "type": [ "number", "null" ], "format": "double" }, "source": { "type": [ "string", "null" ] } } }, "MetaTagDto": { "type": "object", "description": "A meta tag.", "required": [ "content" ], "properties": { "content": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "property": { "type": [ "string", "null" ] } } }, "MetadataSummary": { "type": "object", "description": "Summary of page metadata presence and quality signals.", "required": [ "has_title", "has_description", "has_h1", "has_canonical", "has_og_tags", "has_structured_data", "word_count", "internal_link_count", "external_link_count", "image_count", "images_missing_alt" ], "properties": { "external_link_count": { "type": "integer", "minimum": 0 }, "has_canonical": { "type": "boolean" }, "has_description": { "type": "boolean" }, "has_h1": { "type": "boolean" }, "has_og_tags": { "type": "boolean" }, "has_structured_data": { "type": "boolean" }, "has_title": { "type": "boolean" }, "image_count": { "type": "integer", "minimum": 0 }, "images_missing_alt": { "type": "integer", "minimum": 0 }, "internal_link_count": { "type": "integer", "minimum": 0 }, "word_count": { "type": "integer", "minimum": 0 } } }, "MetricResponse": { "type": "object", "required": [ "metric_name", "metric_type", "value", "attributes", "timestamp" ], "properties": { "attributes": {}, "metric_name": { "type": "string" }, "metric_type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "value": { "type": "number", "format": "double" } } }, "ModelConfigResponse": { "type": "object", "required": [ "model_type", "weights", "thresholds", "updated_at" ], "properties": { "model_type": { "type": "string" }, "thresholds": {}, "updated_at": { "type": "string", "format": "date-time" }, "weights": {} } }, "MonitorResponse": { "type": "object", "required": [ "id", "name", "keywords", "companies", "authors", "industries", "seniority_filter", "monitor_type", "priority", "enabled", "created_at", "updated_at" ], "properties": { "authors": { "type": "array", "items": { "type": "string" } }, "companies": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "industries": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "last_polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "monitor_type": { "type": "string" }, "name": { "type": "string" }, "priority": { "type": "string" }, "seniority_filter": { "type": "array", "items": { "type": "string" } }, "stealth_config": {}, "updated_at": { "type": "string", "format": "date-time" } } }, "NotificationSettingDto": { "type": "object", "required": [ "id", "alert_type", "channel", "frequency", "enabled" ], "properties": { "alert_type": { "type": "string" }, "channel": { "type": "string" }, "enabled": { "type": "boolean" }, "frequency": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "NotificationSettingsResponse": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationSettingDto" } } } }, "OAuthClientConfigRequest": { "type": "object", "description": "Tenant-scoped Google OAuth client configuration. The client secret is\naccepted for encrypted storage but is never returned by the API.", "required": [ "client_id", "client_secret" ], "properties": { "client_id": { "type": "string", "description": "Google OAuth client ID." }, "client_secret": { "type": "string", "description": "Google OAuth client secret." } } }, "OAuthClientConfigStatus": { "type": "object", "description": "Redacted status for the effective Google OAuth client configuration.", "required": [ "configured", "source" ], "properties": { "client_id_hint": { "type": [ "string", "null" ], "description": "Redacted client-ID hint. The client secret is never returned." }, "configured": { "type": "boolean", "description": "Whether an OAuth client is available for this account." }, "source": { "type": "string", "description": "Credential source: `tenant`, `environment`, or `none`." }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Last tenant configuration update; absent for environment fallback." } } }, "ObservationResponse": { "type": "object", "required": [ "id", "experiment_id", "metric", "value", "observed_at" ], "properties": { "experiment_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "metric": { "type": "string" }, "observed_at": { "type": "string", "format": "date-time" }, "value": { "type": "number", "format": "double" } } }, "OperationDetail": { "type": "object", "description": "Detailed view of a single operation.", "required": [ "operation_name", "description", "capabilities", "is_available" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "config_schema": {}, "description": { "type": "string" }, "is_available": { "type": "boolean" }, "operation_name": { "type": "string" } } }, "OperationListResponse": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "items": { "type": "string" } } } }, "OperationSummary": { "type": "object", "description": "Summary of a registered operation.", "required": [ "operation_name", "description", "capabilities", "is_available" ], "properties": { "capabilities": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "is_available": { "type": "boolean" }, "operation_name": { "type": "string" } } }, "OperationsListResponse": { "type": "object", "description": "Response wrapping a list of operations.", "required": [ "operations", "total" ], "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/OperationSummary" } }, "total": { "type": "integer", "minimum": 0 } } }, "ParseRequest": { "type": "object", "description": "Request to parse JSON/CSV to Parquet", "required": [ "input_path", "output_prefix", "format" ], "properties": { "batch_size": { "type": [ "integer", "null" ], "minimum": 0 }, "delimiter": { "type": [ "string", "null" ] }, "format": { "type": "string", "description": "\"json\" or \"csv\"" }, "has_header": { "type": [ "boolean", "null" ] }, "input_path": { "type": "string" }, "output_prefix": { "type": "string" }, "record_path": { "type": [ "string", "null" ] }, "use_simd": { "type": [ "boolean", "null" ] } } }, "ParseResponse": { "type": "object", "description": "Response from parse operation", "required": [ "output_prefix", "partition_count", "total_rows", "total_bytes" ], "properties": { "output_prefix": { "type": "string" }, "partition_count": { "type": "integer", "format": "int64", "minimum": 0 }, "total_bytes": { "type": "integer", "format": "int64", "minimum": 0 }, "total_rows": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PatchListResponse": { "type": "object", "description": "List of patches.", "required": [ "patches", "total" ], "properties": { "patches": { "type": "array", "items": { "$ref": "#/components/schemas/PatchResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "PatchResponse": { "type": "object", "description": "Response for a pipeline patch.", "required": [ "id", "pipeline_id", "patch_type", "original_config", "proposed_config", "llm_rationale", "status", "created_at" ], "properties": { "applied_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "llm_rationale": { "type": "string" }, "original_config": {}, "patch_type": { "type": "string" }, "pipeline_id": { "type": "string", "format": "uuid" }, "proposed_config": {}, "status": { "type": "string" } } }, "PatternSummary": { "type": "object", "required": [ "pattern", "confidence", "recommendation" ], "properties": { "confidence": { "type": "number", "format": "double" }, "pattern": { "type": "string" }, "recommendation": { "type": "string" } } }, "PayerItem": { "type": "object", "required": [ "canonical_name", "display_name" ], "properties": { "canonical_name": { "type": "string" }, "display_name": { "type": "string" }, "ein": { "type": [ "string", "null" ] }, "is_major": { "type": [ "boolean", "null" ] }, "parent_company": { "type": [ "string", "null" ] }, "payer_type": { "type": [ "string", "null" ] } } }, "PipelineActionResponse": { "type": "object", "description": "Pipeline action response (pause/cancel).", "required": [ "run_id", "action", "previous_status", "new_status" ], "properties": { "action": { "type": "string" }, "new_status": { "type": "string" }, "previous_status": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" } } }, "PipelineListResponse": { "type": "object", "description": "List of enrichment pipelines.", "required": [ "pipelines", "total" ], "properties": { "pipelines": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "PipelineOverview": { "type": "object", "required": [ "total_deals", "total_value_cents", "avg_deal_value_cents", "weighted_pipeline_cents", "stages" ], "properties": { "avg_days_in_pipeline": { "type": [ "number", "null" ], "format": "double" }, "avg_deal_value_cents": { "type": "integer", "format": "int64" }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/StageMetrics" } }, "total_deals": { "type": "integer", "format": "int64" }, "total_value_cents": { "type": "integer", "format": "int64" }, "weighted_pipeline_cents": { "type": "integer", "format": "int64" } } }, "PipelineResponse": { "type": "object", "description": "Response for an enrichment pipeline.", "required": [ "id", "name", "status", "steps", "step_count", "version", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "pipeline_kind": { "type": [ "string", "null" ] }, "schedule": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "step_count": { "type": "integer", "minimum": 0 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineStepDto" } }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "PipelineRunDetail": { "type": "object", "required": [ "id", "pipeline_name", "status", "records_fetched", "records_parsed", "records_loaded", "records_skipped", "errors", "config", "started_at" ], "properties": { "completed_at": { "type": [ "string", "null" ] }, "config": {}, "errors": {}, "id": { "type": "string", "format": "uuid" }, "pipeline_name": { "type": "string" }, "records_fetched": { "type": "integer", "format": "int64" }, "records_loaded": { "type": "integer", "format": "int64" }, "records_parsed": { "type": "integer", "format": "int64" }, "records_skipped": { "type": "integer", "format": "int64" }, "started_at": { "type": "string" }, "status": { "type": "string" } } }, "PipelineRunResponse": { "type": "object", "description": "Response for a pipeline run.", "required": [ "id", "pipeline_id", "status", "step_results", "rows_processed", "started_at" ], "properties": { "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "pipeline_id": { "type": "string", "format": "uuid" }, "rows_processed": { "type": "integer", "minimum": 0 }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "step_results": { "type": "array", "items": { "$ref": "#/components/schemas/StepResultDto" } } } }, "PipelineRunSummary": { "type": "object", "required": [ "id", "pipeline_name", "status", "records_loaded", "started_at" ], "properties": { "completed_at": { "type": [ "string", "null" ] }, "id": { "type": "string" }, "pipeline_name": { "type": "string" }, "records_loaded": { "type": "integer", "format": "int64" }, "started_at": { "type": "string" }, "status": { "type": "string" } } }, "PipelineStatusResponse": { "type": "object", "required": [ "recent_runs", "source_counts" ], "properties": { "recent_runs": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineRunSummary" } }, "source_counts": { "$ref": "#/components/schemas/SourceCounts" } } }, "PipelineStepDto": { "type": "object", "description": "A step in a pipeline.", "required": [ "name", "operation" ], "properties": { "config": {}, "depends_on": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "operation": { "type": "string" } } }, "PolicyCommentResponse": { "type": "object", "description": "Governance policy comment response DTO.", "required": [ "id", "policy_id", "author_id", "comment", "created_at" ], "properties": { "author_id": { "type": "string" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "policy_id": { "type": "string", "format": "uuid" } } }, "PolicyResponse": { "type": "object", "description": "Governance policy response DTO.", "required": [ "id", "account_id", "policy_type", "resource_id", "resource_type", "requested_by", "status", "created_at", "updated_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "decision": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "justification": { "type": [ "string", "null" ] }, "policy_type": { "type": "string" }, "requested_by": { "type": "string" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" }, "review_notes": { "type": [ "string", "null" ] }, "reviewed_by": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "PollResponse": { "type": "object", "required": [ "status", "mentions_found", "message" ], "properties": { "mentions_found": { "type": "integer", "format": "int64" }, "message": { "type": "string" }, "status": { "type": "string" } } }, "PostingNorms": { "type": "object", "required": [ "self_promo_allowed", "link_posts_allowed", "flair_required", "common_formats" ], "properties": { "common_formats": { "type": "array", "items": { "type": "string" } }, "flair_required": { "type": "boolean" }, "link_posts_allowed": { "type": "boolean" }, "min_karma": { "type": [ "integer", "null" ], "format": "int32" }, "self_promo_allowed": { "type": "boolean" } } }, "ProfileRequest": { "type": "object", "required": [ "dataset_id" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" } } }, "ProfileResponse": { "type": "object", "required": [ "id", "dataset_id", "row_count", "null_rates", "type_distribution", "computed_at" ], "properties": { "computed_at": { "type": "string", "format": "date-time" }, "dataset_id": { "type": "string", "format": "uuid" }, "id": { "type": "string", "format": "uuid" }, "null_rates": {}, "row_count": { "type": "integer", "format": "int64" }, "type_distribution": {} } }, "ProjectResponse": { "type": "object", "required": [ "id", "account_id", "name", "public_key", "config", "allowed_origins", "enabled", "created_at", "updated_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "allowed_origins": { "type": "array", "items": { "type": "string" } }, "config": {}, "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProvisionTenantRequest": { "type": "object", "required": [ "account_name", "owner_email" ], "properties": { "account_name": { "type": "string", "description": "Display name for the tenant account." }, "api_domain": { "type": [ "string", "null" ], "description": "Product API domain, e.g. api.scaleintelligence.co." }, "api_key_name": { "type": [ "string", "null" ], "description": "API key name. Defaults to Full Access Production Key." }, "app_domain": { "type": [ "string", "null" ], "description": "Product app domain, e.g. app.scaleintelligence.co." }, "domain": { "type": [ "string", "null" ], "description": "Primary organization/product domain, e.g. scaleintelligence.co." }, "organization": { "type": [ "string", "null" ], "description": "Optional organization name. Defaults to account_name." }, "owner_email": { "type": "string", "description": "Owner/contact email for the tenant. Stored as account email and metadata." }, "owner_name": { "type": [ "string", "null" ], "description": "Optional owner/contact display name." }, "scopes": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Token scopes. Defaults to full access [\"*\"]." }, "tier": { "type": [ "string", "null" ], "description": "Account tier. Defaults to enterprise." } } }, "ProvisionTenantResponse": { "type": "object", "required": [ "account_id", "account_name", "account_email", "tier", "api_key", "key_prefix", "scopes", "domains", "created_at" ], "properties": { "account_email": { "type": "string" }, "account_id": { "type": "string", "format": "uuid" }, "account_name": { "type": "string" }, "api_key": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "domains": { "type": "array", "items": { "type": "string" } }, "key_prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string" } } }, "ProxyEndpointResponse": { "type": "object", "description": "Response for a proxy endpoint.", "required": [ "id", "url", "provider", "proxy_type", "avg_latency_ms", "success_rate", "healthy" ], "properties": { "avg_latency_ms": { "type": "number", "format": "double" }, "geo": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GeoLocationDto" } ] }, "healthy": { "type": "boolean" }, "id": { "type": "string", "format": "uuid" }, "last_checked": { "type": [ "string", "null" ], "format": "date-time" }, "provider": { "type": "string" }, "proxy_type": { "type": "string" }, "success_rate": { "type": "number", "format": "double" }, "url": { "type": "string" } } }, "ProxyListResponse": { "type": "object", "description": "List of proxy endpoints.", "required": [ "proxies", "healthy_count", "total_count" ], "properties": { "healthy_count": { "type": "integer", "minimum": 0 }, "proxies": { "type": "array", "items": { "$ref": "#/components/schemas/ProxyEndpointResponse" } }, "total_count": { "type": "integer", "minimum": 0 } } }, "PublishRequest": { "type": "object", "description": "Request to publish a document.", "properties": { "target_url": { "type": [ "string", "null" ], "description": "Target URL where the content will be published" } } }, "PurgeRequest": { "type": "object", "description": "Request to purge queue items.", "required": [ "queue_name" ], "properties": { "older_than_secs": { "type": [ "integer", "null" ], "format": "int64", "description": "Purge items older than N seconds", "minimum": 0 }, "queue_name": { "type": "string" }, "statuses": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Purge items in these statuses (default: completed, failed)" } } }, "QualityPipelineRequest": { "type": "object", "required": [ "url", "site_id" ], "properties": { "max_pages": { "type": [ "integer", "null" ], "format": "int32", "description": "Maximum pages to crawl (default: 30)", "minimum": 0 }, "quality_threshold": { "type": [ "integer", "null" ], "format": "int32", "description": "Minimum quality score threshold (0-100, default: 30)", "minimum": 0 }, "site_id": { "type": "string", "format": "uuid", "description": "Site ID to associate results with" }, "url": { "type": "string", "description": "URL to run the quality pipeline against" } } }, "QualityPipelineResponse": { "type": "object", "required": [ "status", "workflow_id", "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "string" }, "workflow_id": { "type": "string" } } }, "QualityProfileDto": { "type": "object", "required": [ "min_quality_score", "min_word_count", "dedup_threshold", "require_references" ], "properties": { "dedup_threshold": { "type": "number", "format": "float" }, "min_quality_score": { "type": "number", "format": "double" }, "min_word_count": { "type": "integer", "minimum": 0 }, "require_references": { "type": "boolean" } } }, "QualityProfileResponse": { "type": "object", "required": [ "id", "profile_type", "total_rows", "passed_rows", "failed_rows", "duplicate_count", "dimensions", "filter_config", "computed_at" ], "properties": { "computed_at": { "type": "string", "format": "date-time" }, "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "dimensions": {}, "duplicate_count": { "type": "integer", "format": "int64" }, "failed_rows": { "type": "integer", "format": "int64" }, "filter_config": {}, "id": { "type": "string", "format": "uuid" }, "passed_rows": { "type": "integer", "format": "int64" }, "profile_type": { "type": "string" }, "quality_score": { "type": [ "number", "null" ], "format": "double" }, "total_rows": { "type": "integer", "format": "int64" } } }, "QueueActionResponse": { "type": "object", "description": "Response for retry or purge actions.", "required": [ "action", "affected", "queue_name" ], "properties": { "action": { "type": "string" }, "affected": { "type": "integer", "minimum": 0 }, "queue_name": { "type": "string" } } }, "QueueItemResponse": { "type": "object", "description": "Response for a queue item.", "required": [ "id", "queue_name", "status", "priority", "payload", "attempts", "max_retries", "created_at", "updated_at" ], "properties": { "attempts": { "type": "integer", "format": "int32", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "locked_until": { "type": [ "string", "null" ], "format": "date-time" }, "max_retries": { "type": "integer", "format": "int32", "minimum": 0 }, "payload": {}, "priority": { "type": "integer", "format": "int32" }, "queue_name": { "type": "string" }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "QueueListResponse": { "type": "object", "description": "List of queue items.", "required": [ "items", "total" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueueItemResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "QueueResponse": { "type": "object", "description": "Governance policy queue response.", "required": [ "policies", "total" ], "properties": { "policies": { "type": "array", "items": { "$ref": "#/components/schemas/PolicyResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "QueueStatsResponse": { "type": "object", "description": "Queue statistics.", "required": [ "queue_name", "pending", "processing", "completed", "failed", "dead_letter", "total" ], "properties": { "completed": { "type": "integer", "format": "int64" }, "dead_letter": { "type": "integer", "format": "int64" }, "failed": { "type": "integer", "format": "int64" }, "pending": { "type": "integer", "format": "int64" }, "processing": { "type": "integer", "format": "int64" }, "queue_name": { "type": "string" }, "total": { "type": "integer", "format": "int64" } } }, "RateLimitDto": { "type": "object", "description": "Rate limit info for an enrichment source.", "required": [ "requests_per_minute" ], "properties": { "requests_per_day": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "requests_per_minute": { "type": "integer", "format": "int32", "minimum": 0 } } }, "RateResult": { "type": "object", "required": [ "code", "code_type", "hospital_name", "charge_type" ], "properties": { "charge_type": { "type": "string" }, "code": { "type": "string" }, "code_type": { "type": "string" }, "consumer_description": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "hospital_city": { "type": [ "string", "null" ] }, "hospital_name": { "type": "string" }, "hospital_state": { "type": [ "string", "null" ] }, "median_allowed_amount": { "type": [ "number", "null" ], "format": "double" }, "payer_name": { "type": [ "string", "null" ] }, "pct_of_medicare": { "type": [ "number", "null" ], "format": "double" }, "rate": { "type": [ "number", "null" ], "format": "double" }, "source_date": { "type": [ "string", "null" ] } } }, "RecentAuditDto": { "type": "object", "required": [ "audit_id", "site_id", "domain", "status" ], "properties": { "audit_id": { "type": "string", "format": "uuid" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "domain": { "type": "string" }, "issues_found": { "type": [ "integer", "null" ], "format": "int32" }, "pages_crawled": { "type": [ "integer", "null" ], "format": "int32" }, "score": { "type": [ "integer", "null" ], "format": "int32" }, "site_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "RecommendRequest": { "type": "object", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "format": "uuid" } } }, "RecommendResponse": { "type": "object", "required": [ "recommendations" ], "properties": { "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordRecommendation" } } } }, "RecordEventRequest": { "type": "object", "required": [ "site_id", "url", "loop_type", "issue_category", "status" ], "properties": { "diagnosis": { "type": [ "string", "null" ], "description": "Diagnosis text (required when transitioning to \"diagnosed\")" }, "fix_description": { "type": [ "string", "null" ], "description": "Description of the fix (required when transitioning to \"fix_suggested\")" }, "issue_category": { "type": "string" }, "loop_type": { "type": "string" }, "metadata": {}, "site_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "url": { "type": "string" } } }, "RecordSignalRequest": { "type": "object", "required": [ "signal_type", "source", "data" ], "properties": { "data": {}, "lead_id": { "type": [ "string", "null" ], "format": "uuid" }, "signal_type": { "type": "string" }, "source": { "type": "string" }, "strength": { "type": "number", "format": "double" } } }, "RecrawlPolicyDto": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "never" ] } } }, { "type": "object", "required": [ "interval_secs", "type" ], "properties": { "interval_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "fixed_interval" ] } } }, { "type": "object", "required": [ "min_interval_secs", "max_interval_secs", "type" ], "properties": { "max_interval_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "min_interval_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "adaptive" ] } } }, { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "on_change" ] } } }, { "type": "object", "required": [ "high_interval_secs", "low_interval_secs", "type" ], "properties": { "high_interval_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "low_interval_secs": { "type": "integer", "format": "int64", "minimum": 0 }, "type": { "type": "string", "enum": [ "priority_based" ] } } } ], "description": "Re-crawl policy (API-facing DTO)." }, "RedditComment": { "type": "object", "description": "A single Reddit comment, shaped consistently with `SubredditPost` so the\nreddit-intelligence CrawlkitProvider can parse posts and comments the same\nway (id + body + subreddit + score + created_utc, plus comment-specific\nauthor/permalink/parent fields).", "required": [ "id", "body", "subreddit", "score", "created_utc" ], "properties": { "author": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "created_utc": { "type": "number", "format": "double" }, "id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "permalink": { "type": [ "string", "null" ] }, "score": { "type": "integer", "format": "int64" }, "subreddit": { "type": "string" } } }, "RedditPostMetrics": { "type": "object", "description": "Current engagement metrics for a single Reddit post, looked up by id.\n\nShaped so the OpenRecipe reddit-metrics-collector can read the same fields\nit currently parses out of Arctic Shift's `posts/ids` response (`score`,\n`num_comments`, `upvote_ratio`, awards), but served through crawlkit so the\ncollector no longer hits arctic-shift directly. Genuinely-unknown values are\n`null`, never zeroed placeholders. `source` names the upstream that produced\nthe numbers (currently `arctic_shift`).", "required": [ "id", "subreddit", "score", "num_comments", "created_utc", "source" ], "properties": { "author": { "type": [ "string", "null" ] }, "award_count": { "type": [ "integer", "null" ], "format": "int64" }, "created_utc": { "type": "number", "format": "double" }, "id": { "type": "string", "description": "Post id, normalized to the `t3_` fullname form." }, "num_comments": { "type": "integer", "format": "int64" }, "permalink": { "type": [ "string", "null" ] }, "score": { "type": "integer", "format": "int64" }, "source": { "type": "string", "description": "Which upstream produced the numbers (currently `arctic_shift`)." }, "subreddit": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "upvote_ratio": { "type": [ "number", "null" ], "format": "double" }, "url": { "type": [ "string", "null" ] } } }, "RedirectCheckRequest": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "RedirectDto": { "type": "object", "required": [ "configured", "is_permanent" ], "properties": { "configured": { "type": "boolean" }, "from": { "type": [ "string", "null" ] }, "is_permanent": { "type": "boolean" }, "status_code": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "to": { "type": [ "string", "null" ] } } }, "RefreshViewsResponse": { "type": "object", "required": [ "views_refreshed" ], "properties": { "views_refreshed": { "type": "array", "items": { "type": "string" } } } }, "RegisterArtifactRequest": { "type": "object", "required": [ "source_url" ], "properties": { "content_type": { "type": [ "string", "null" ] }, "discovery_context": { "type": [ "string", "null" ] }, "file_extension": { "type": [ "string", "null" ] }, "site_url": { "type": [ "string", "null" ] }, "source_url": { "type": "string" } } }, "RegisterTableRequest": { "type": "object", "description": "Request to register a Parquet file as a DataFusion table", "required": [ "table_name", "parquet_path" ], "properties": { "parquet_path": { "type": "string" }, "table_name": { "type": "string" } } }, "RegisterViewRequest": { "type": "object", "description": "Request to register a Parquet file/glob as a DuckDB view", "required": [ "view_name", "parquet_path" ], "properties": { "parquet_path": { "type": "string" }, "view_name": { "type": "string" } } }, "RejectApprovalRequest": { "type": "object", "description": "Request to reject a document with feedback.", "required": [ "comments" ], "properties": { "comments": { "type": "string" } } }, "RemediationDto": { "type": "object", "required": [ "summary", "steps", "effort" ], "properties": { "commands": { "type": "array", "items": { "type": "string" } }, "effort": { "type": "string" }, "file_changes": { "type": "array", "items": { "$ref": "#/components/schemas/FileChangeDto" } }, "steps": { "type": "array", "items": { "type": "string" } }, "summary": { "type": "string" } } }, "RemoveClientResponse": { "type": "object", "required": [ "removed" ], "properties": { "removed": { "type": "boolean" } } }, "RepairSpiderRequest": { "type": "object", "description": "Request to repair a spider's broken selectors.", "required": [ "failures" ], "properties": { "failures": { "type": "array", "items": { "$ref": "#/components/schemas/AiFieldFailure" } } } }, "RepairSpiderResponse": { "type": "object", "description": "Response from spider repair.", "required": [ "spider", "fields_repaired" ], "properties": { "fields_repaired": { "type": "integer", "minimum": 0 }, "spider": { "$ref": "#/components/schemas/SpiderResponse" } } }, "ReportRequest": { "type": "object", "required": [ "site_id" ], "properties": { "format": { "type": "string" }, "include_llm_context": { "type": "boolean" }, "site_id": { "type": "string", "format": "uuid" } } }, "ReportResponse": { "type": "object", "required": [ "format", "report" ], "properties": { "format": { "type": "string" }, "report": {} } }, "RequestApprovalRequest": { "type": "object", "description": "Request to submit a document for approval.", "properties": { "approval_type": { "type": [ "string", "null" ] } } }, "ResolveRequest": { "type": "object", "description": "Request to resolve an incident.", "required": [ "root_cause", "remediation" ], "properties": { "postmortem_url": { "type": [ "string", "null" ] }, "remediation": { "type": "string" }, "root_cause": { "type": "string" } } }, "RetryRequest": { "type": "object", "description": "Request to retry a failed queue item.", "required": [ "item_id" ], "properties": { "delay_secs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "item_id": { "type": "string", "format": "uuid" } } }, "ReviewPolicyRequest": { "type": "object", "description": "Request to review a governance policy.", "required": [ "decision", "reviewed_by" ], "properties": { "decision": { "type": "string", "description": "Decision: \"approved\", \"rejected\", or \"escalated\"" }, "review_notes": { "type": [ "string", "null" ] }, "reviewed_by": { "type": "string" } } }, "RootCauseDto": { "type": "object", "required": [ "category", "explanation", "confidence" ], "properties": { "category": { "type": "string" }, "confidence": { "type": "number", "format": "float" }, "evidence": { "type": "array", "items": { "type": "string" } }, "explanation": { "type": "string" } } }, "RowListResponse": { "type": "object", "description": "List of dataset rows.", "required": [ "rows", "total" ], "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRowResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "RunAuditRequest": { "type": "object", "required": [ "url", "site_id" ], "properties": { "max_pages": { "type": [ "integer", "null" ], "description": "Maximum pages to crawl (default: 25)", "minimum": 0 }, "site_id": { "type": "string", "format": "uuid", "description": "Site ID to persist results against" }, "url": { "type": "string", "description": "URL to audit" } } }, "RunListResponse": { "type": "object", "description": "List of pipeline runs.", "required": [ "runs", "total" ], "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/PipelineRunResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "RunPipelineRequest": { "type": "object", "description": "Request to start a pipeline run.", "properties": { "dataset_id": { "type": [ "string", "null" ], "format": "uuid" }, "parameters": {} } }, "RunResponse": { "type": "object", "description": "Pipeline run as returned by the runs endpoints.", "required": [ "id", "account_id", "pipeline_id", "status", "step_results", "rows_processed", "started_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "parameters": {}, "pipeline_id": { "type": "string", "format": "uuid" }, "rows_processed": { "type": "integer", "format": "int64" }, "started_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "step_results": {} } }, "RunTemplateRequest": { "type": "object", "description": "Request body for running a workflow template.", "properties": { "dataset_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Back-compat alias for output_dataset_id." }, "input_dataset_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional input dataset to seed the workflow when no rows are otherwise\npresent. Most scrape workflows leave this empty and seed from step config." }, "output_dataset_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Optional output dataset to replace with final workflow rows." }, "parameters": { "type": "object", "description": "Parameter values to resolve `{{param}}` placeholders." } } }, "RunTemplateResponse": { "type": "object", "description": "Response after triggering a workflow run.", "required": [ "run_id", "template_id", "template_name", "status", "message" ], "properties": { "message": { "type": "string" }, "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "template_id": { "type": "string", "format": "uuid" }, "template_name": { "type": "string" } } }, "ScheduleActionResponse": { "type": "object", "required": [ "schedule_type", "status" ], "properties": { "schedule_type": { "type": "string" }, "status": { "type": "string" } } }, "ScheduleStartRequest": { "type": "object", "required": [ "schedule_type" ], "properties": { "entity_id": { "type": [ "string", "null" ] }, "interval_secs": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "schedule_type": { "type": "string" } } }, "ScheduleStatusResponse": { "type": "object", "description": "Response for schedule operations.", "required": [ "pipeline_id", "scheduled" ], "properties": { "cron_expression": { "type": [ "string", "null" ] }, "next_run": { "type": [ "string", "null" ], "format": "date-time" }, "pipeline_id": { "type": "string", "format": "uuid" }, "scheduled": { "type": "boolean" } } }, "ScheduleStopRequest": { "type": "object", "required": [ "schedule_type" ], "properties": { "entity_id": { "type": [ "string", "null" ] }, "schedule_type": { "type": "string" } } }, "ScheduledAuditListResponse": { "type": "object", "required": [ "schedules", "total" ], "properties": { "schedules": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledAuditResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "ScheduledAuditResponse": { "type": "object", "required": [ "id", "site_id", "frequency", "enabled", "max_pages", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "enabled": { "type": "boolean" }, "frequency": { "$ref": "#/components/schemas/AuditScheduleFrequency" }, "id": { "type": "string", "format": "uuid" }, "last_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "max_pages": { "type": "integer", "format": "int32" }, "next_run_at": { "type": [ "string", "null" ], "format": "date-time" }, "site_id": { "type": "string", "format": "uuid" } } }, "SchemaQueryRequest": { "type": "object", "description": "Request to get schema for a view", "required": [ "view_name" ], "properties": { "view_name": { "type": "string" } } }, "SchemaQueryResponse": { "type": "object", "description": "Response with view schema", "required": [ "view_name", "columns" ], "properties": { "columns": { "type": "array", "items": { "$ref": "#/components/schemas/ColumnInfo" } }, "view_name": { "type": "string" } } }, "SchemaRequest": { "type": "object", "required": [ "site_id", "url", "page_type" ], "properties": { "page_type": { "type": "string" }, "site_id": { "type": "string", "format": "uuid" }, "url": { "type": "string" } } }, "SchemaResponse": { "type": "object", "required": [ "page_type", "json_ld" ], "properties": { "json_ld": {}, "page_type": { "type": "string" } } }, "SchemaVersionResponse": { "type": "object", "required": [ "id", "schema_name", "version", "json_schema", "is_active", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "is_active": { "type": "boolean" }, "json_schema": {}, "schema_name": { "type": "string" }, "version": { "type": "integer", "format": "int32" } } }, "ScoreLeadRequest": { "type": "object", "required": [ "lead_data" ], "properties": { "lead_data": {}, "target_company_sizes": { "type": "array", "items": { "type": "string" } }, "target_industries": { "type": "array", "items": { "type": "string" } }, "target_technologies": { "type": "array", "items": { "type": "string" } } } }, "ScoreLeadResponse": { "type": "object", "required": [ "fit_score", "tier", "reasoning" ], "properties": { "fit_score": { "type": "number", "format": "double" }, "reasoning": { "type": "string" }, "tier": { "type": "string" } } }, "ScoreRequest": { "type": "object", "required": [ "dataset_id" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "dimensions": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "ScoreResponse": { "type": "object", "required": [ "dataset_id", "quality_score", "dimensions" ], "properties": { "dataset_id": { "type": "string", "format": "uuid" }, "dimensions": {}, "quality_score": { "type": "number", "format": "double" } } }, "SearchHitNativeId": { "type": "object", "description": "The source's OWN identifier for the content unit a hit addresses.\n\nThe join key against the silver corpus: `native_id` is byte-identical to the\n`SilverRow::record_id` the owning connector's `lakehouse_conform` writes for\nthat same unit (`t3_abc123`, `2028500784237969559`,\n`urn:li:activity:7012345`), and `source` is the connector's stable\n`source_kind` token.\n\nWire-mirrors [`crawlkit_connectors::SourceNativeId`], and — like it — is\nconstructible ONLY from one, so nothing in this crate can present a URL, a\nhash of a URL, or an empty string as a native id.\n\nThe field names are `source` and `native_id` DELIBERATELY: they are the field\nnames of Scale Intelligence's `shared-types::spine_unit::SourceNativeId`, so\nthis object deserializes directly into that type through its validating,\nconstructor-routed deserializer. Renaming either side would not fail loudly —\nit would drop the identity and re-empty the join — so the spelling is pinned\nby a test.\n\nCrawlKit emits the two CONSTITUENTS and never the joined `source:native_id`\nspine `unit_id`: that encoding has exactly one derivation site, and it is the\nconsumer's.", "required": [ "source", "native_id" ], "properties": { "native_id": { "type": "string", "description": "The source-native content id, verbatim — equal to the silver\n`record_id`/`content_id` for the same unit." }, "source": { "type": "string", "description": "The owning connector's `source_kind` (`reddit`, `x`, `linkedin`, …)." } } }, "SearchRatesResponse": { "type": "object", "required": [ "results", "total" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/RateResult" } }, "total": { "type": "integer", "format": "int64" } } }, "SearchRequest": { "type": "object", "description": "A web/document search request from the Scale Intelligence search seam.", "required": [ "query" ], "properties": { "index": { "type": [ "string", "null" ], "description": "Index/collection to search (e.g. `\"web\"`). Defaults to `\"web\"`." }, "k": { "type": [ "integer", "null" ], "format": "int32", "description": "Max number of ranked results to return (default 8, clamped to 20).", "minimum": 0 }, "query": { "type": "string", "description": "Natural-language search query." } } }, "SearchResponse": { "type": "object", "description": "A web/document search response with HONEST provenance.\n\n`honesty_label` is one of:\n- `\"live\"` — a real backend was queried successfully (results may be empty\n if a provisioned index had no matches).\n- `\"empty\"` — the index is unprovisioned (no vector backend / embeddings);\n results are intentionally empty. NEVER fabricated.\n- `\"degraded\"` — the backend was configured but the query failed; results are\n empty and `degraded_reason` explains why.", "required": [ "contract_version", "index", "results", "count", "honesty_label" ], "properties": { "contract_version": { "type": "integer", "format": "int32", "description": "Contract version of this response body.\n\n`1` — hits carry `{title, url, snippet, domain, score}` only.\n`2` — hits MAY additionally carry `source_native_id`.\n\nThis exists to keep two very different situations apart, which a bare\nabsent field cannot: \"this server is too old to supply native ids at all\"\n(`< 2`) versus \"this server supplies them and this particular hit honestly\nhas none\" (`>= 2`, key absent). Without it a consumer that found no ids\ncould not tell a capability gap from an honest absence, and would have no\nsafe way to decide whether an empty lineage join is a bug or the truth.", "minimum": 0 }, "count": { "type": "integer", "description": "Number of results (== `results.len()`), for convenience.", "minimum": 0 }, "degraded_reason": { "type": [ "string", "null" ], "description": "Present only when `honesty_label == \"degraded\"`." }, "honesty_label": { "type": "string", "description": "Honest provenance label: `\"live\" | \"empty\" | \"degraded\"`." }, "index": { "type": "string", "description": "The index/collection that was searched." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResultItem" }, "description": "Ranked results (empty for `empty`/`degraded`)." } } }, "SearchResultItem": { "type": "object", "description": "A single ranked search result.", "required": [ "title", "url", "snippet", "score" ], "properties": { "domain": { "type": [ "string", "null" ], "description": "Source domain, when known." }, "score": { "type": "number", "format": "float", "description": "Backend relevance score." }, "snippet": { "type": "string", "description": "Short content snippet / excerpt." }, "source_native_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SearchHitNativeId", "description": "The source's own id for this content unit, when the URL names one.\n\nABSENT — the key omitted entirely, not null — whenever no native id\nhonestly exists: a generic web page, a subreddit listing, an X profile, a\nLinkedIn company page, or a source whose public URL is keyed differently\nthan its silver rows. A consumer MUST treat absence as \"this hit cannot be\njoined to the corpus\" and must NOT substitute `url`: two hits with the\nsame URL are not known to be the same silver row, which is the confusion\nthis field exists to end." } ] }, "title": { "type": "string", "description": "Document/page title." }, "url": { "type": "string", "description": "Canonical URL." } } }, "SelectorMatchDto": { "type": "object", "description": "A CSS selector that matches the target text.", "required": [ "selector", "matched_text", "specificity", "confidence" ], "properties": { "confidence": { "type": "number", "format": "double" }, "matched_text": { "type": "string" }, "selector": { "type": "string" }, "specificity": { "type": "string" } } }, "SeoReportListResponse": { "type": "object", "required": [ "reports", "total" ], "properties": { "reports": { "type": "array", "items": { "$ref": "#/components/schemas/SeoReportResponse" } }, "total": { "type": "integer", "format": "int32" } } }, "SeoReportResponse": { "type": "object", "required": [ "id", "site_url", "month", "format", "created_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "format": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "metrics_json": {}, "month": { "type": "string" }, "narrative_md": { "type": [ "string", "null" ] }, "site_url": { "type": "string" } } }, "SerpCompetitor": { "type": "object", "required": [ "url", "domain" ], "properties": { "domain": { "type": "string" }, "position": { "type": [ "integer", "null" ], "format": "int32" }, "title": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "SessionEndRequest": { "type": "object", "required": [ "session_id" ], "properties": { "exit_page": { "type": [ "string", "null" ] }, "session_id": { "type": "string" } } }, "SessionResponse": { "type": "object", "required": [ "id", "visitor_id", "started_at", "last_activity_at", "page_count", "event_count", "device", "is_bot" ], "properties": { "device": {}, "duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "ended_at": { "type": [ "string", "null" ], "format": "date-time" }, "entry_page": { "type": [ "string", "null" ] }, "event_count": { "type": "integer", "format": "int32" }, "exit_page": { "type": [ "string", "null" ] }, "geo": {}, "id": { "type": "string" }, "is_bot": { "type": "boolean" }, "last_activity_at": { "type": "string", "format": "date-time" }, "page_count": { "type": "integer", "format": "int32" }, "started_at": { "type": "string", "format": "date-time" }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "visitor_id": { "type": "string" } } }, "SessionStartRequest": { "type": "object", "required": [ "session_id", "visitor_id" ], "properties": { "device": {}, "entry_page": { "type": [ "string", "null" ] }, "geo": {}, "session_id": { "type": "string" }, "user_id": { "type": [ "string", "null" ], "format": "uuid" }, "visitor_id": { "type": "string" } } }, "SettingUpdate": { "type": "object", "required": [ "alert_type", "channel", "enabled" ], "properties": { "alert_type": { "type": "string" }, "channel": { "type": "string" }, "enabled": { "type": "boolean" }, "frequency": { "type": [ "string", "null" ] }, "site_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "SharedKeyword": { "type": "object", "description": "A keyword that both our site and competitors rank for.", "required": [ "keyword", "competitor_best_position", "competitor_domain" ], "properties": { "competitor_best_position": { "type": "number", "format": "double" }, "competitor_domain": { "type": "string" }, "keyword": { "type": "string" }, "monthly_volume": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "our_position": { "type": [ "number", "null" ], "format": "double" } } }, "SignalResponse": { "type": "object", "required": [ "id", "signal_type", "source", "data", "strength", "detected_at" ], "properties": { "data": {}, "detected_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "lead_id": { "type": [ "string", "null" ], "format": "uuid" }, "signal_type": { "type": "string" }, "source": { "type": "string" }, "strength": { "type": "number", "format": "double" } } }, "SimulationAssumptionDto": { "type": "object", "required": [ "name", "distribution", "params" ], "properties": { "distribution": { "type": "string" }, "name": { "type": "string" }, "params": {} } }, "SimulationRequest": { "type": "object", "description": "Request to run a Monte Carlo simulation.", "required": [ "scenario", "assumptions" ], "properties": { "assumptions": { "type": "array", "items": { "$ref": "#/components/schemas/SimulationAssumptionDto" } }, "horizon_months": { "type": "integer", "format": "int32", "minimum": 0 }, "iterations": { "type": "integer", "format": "int32", "minimum": 0 }, "scenario": { "type": "string" }, "site_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "SimulationResponse": { "type": "object", "required": [ "scenario", "iterations", "p5", "p25", "p50", "p75", "p95", "mean", "probability_of_loss", "expected_value", "value_at_risk_95" ], "properties": { "expected_value": { "type": "number", "format": "double" }, "iterations": { "type": "integer", "format": "int32", "minimum": 0 }, "mean": { "type": "number", "format": "double" }, "p25": { "type": "number", "format": "double" }, "p5": { "type": "number", "format": "double" }, "p50": { "type": "number", "format": "double" }, "p75": { "type": "number", "format": "double" }, "p95": { "type": "number", "format": "double" }, "probability_of_loss": { "type": "number", "format": "double" }, "scenario": { "type": "string" }, "value_at_risk_95": { "type": "number", "format": "double" } } }, "SiteIdParam": { "type": "object", "description": "Common query param for endpoints that need a site_id.", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "format": "uuid" } } }, "SiteListResponse": { "type": "object", "required": [ "sites", "total" ], "properties": { "sites": { "type": "array", "items": { "$ref": "#/components/schemas/SiteResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "SiteResponse": { "type": "object", "required": [ "id", "domain", "site_url", "gsc_connected", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "domain": { "type": "string" }, "framework": { "type": [ "string", "null" ] }, "gsc_connected": { "type": "boolean" }, "gsc_property_url": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "latest_audit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LatestAuditSummary" } ] }, "site_url": { "type": "string" }, "stealth_config": {}, "updated_at": { "type": "string", "format": "date-time" } } }, "SiteStatusResponse": { "type": "object", "required": [ "site_id", "pages_crawled", "issues_found", "critical_count", "high_count" ], "properties": { "critical_count": { "type": "integer", "format": "int32" }, "high_count": { "type": "integer", "format": "int32" }, "issues_found": { "type": "integer", "format": "int32" }, "last_audit_at": { "type": [ "string", "null" ], "format": "date-time" }, "latest_score": { "type": [ "integer", "null" ], "format": "int32" }, "pages_crawled": { "type": "integer", "format": "int32" }, "site_id": { "type": "string", "format": "uuid" } } }, "SitemapDiscoverRequest": { "type": "object", "description": "Request to discover and parse sitemaps for a URL.", "required": [ "url" ], "properties": { "url": { "type": "string", "description": "Either a sitemap URL directly (e.g. https://crawlkit.app/sitemap.xml)\nor a site URL whose sitemaps are discovered via robots.txt and the\nconventional /sitemap.xml and /sitemap_index.xml locations." } } }, "SitemapDiscoverResponse": { "type": "object", "description": "Response from sitemap discovery.", "required": [ "url", "discovered_via", "sitemaps", "total_urls" ], "properties": { "discovered_via": { "type": "string", "description": "How the sitemap candidates were found: \"direct\", \"robots_txt\", or\n\"well_known\"." }, "sitemaps": { "type": "array", "items": { "$ref": "#/components/schemas/DiscoveredSitemap" }, "description": "Parsed sitemaps with entry counts." }, "total_urls": { "type": "integer", "description": "Total page URLs found across all parsed sitemaps.", "minimum": 0 }, "url": { "type": "string", "description": "The validated input URL." } } }, "SnapshotQuery": { "type": "object", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "format": "uuid" } } }, "SourceCounts": { "type": "object", "required": [ "hospitals", "providers", "billing_codes", "hospital_rates", "payers", "data_sources" ], "properties": { "billing_codes": { "type": "integer", "format": "int64" }, "data_sources": { "type": "integer", "format": "int64" }, "hospital_rates": { "type": "integer", "format": "int64" }, "hospitals": { "type": "integer", "format": "int64" }, "payers": { "type": "integer", "format": "int64" }, "providers": { "type": "integer", "format": "int64" } } }, "SourceListResponse": { "type": "object", "description": "List of enrichment sources.", "required": [ "sources", "total" ], "properties": { "sources": { "type": "array", "items": { "$ref": "#/components/schemas/EnrichmentSourceResponse" } }, "total": { "type": "integer", "minimum": 0 } } }, "SpanResponse": { "type": "object", "required": [ "trace_id", "span_id", "service_name", "operation", "kind", "start_time", "end_time", "duration_ms", "status", "attributes", "events", "resource" ], "properties": { "attributes": {}, "duration_ms": { "type": "integer", "format": "int64" }, "end_time": { "type": "string", "format": "date-time" }, "events": {}, "kind": { "type": "string" }, "operation": { "type": "string" }, "parent_span_id": { "type": [ "string", "null" ] }, "resource": {}, "service_name": { "type": "string" }, "span_id": { "type": "string" }, "start_time": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "status_message": { "type": [ "string", "null" ] }, "trace_id": { "type": "string" } } }, "SpiderFactoryItem": { "type": "object", "description": "Status of a single spider build in a batch.", "required": [ "spider_id", "url", "status", "workflow_key" ], "properties": { "spider_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "url": { "type": "string" }, "workflow_key": { "type": "string" } } }, "SpiderFactoryRequest": { "type": "object", "description": "Request to batch-create spiders for multiple URLs.", "required": [ "urls", "data_type" ], "properties": { "auto_deploy": { "type": "boolean", "description": "Whether to auto-deploy spiders after successful build (default: false)." }, "data_type": { "type": "string", "description": "Data type hint (e.g. \"ecommerce\", \"news\", \"generic\")." }, "schema": { "description": "Optional JSON schema the spider output should conform to." }, "urls": { "type": "array", "items": { "type": "string" }, "description": "Target URLs to create spiders for." } } }, "SpiderFactoryResponse": { "type": "object", "description": "Response from the spider factory batch endpoint.", "required": [ "batch_id", "total", "items" ], "properties": { "batch_id": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SpiderFactoryItem" } }, "total": { "type": "integer", "minimum": 0 } } }, "SpiderHealthResponse": { "type": "object", "description": "Spider health status.", "required": [ "spider_id", "status", "overall_completeness", "field_health", "sample_size" ], "properties": { "field_health": { "type": "array", "items": { "$ref": "#/components/schemas/FieldHealthDto" } }, "last_checked": { "type": [ "string", "null" ], "format": "date-time" }, "overall_completeness": { "type": "number", "format": "double" }, "sample_size": { "type": "integer", "format": "int32", "minimum": 0 }, "spider_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "SpiderListResponse": { "type": "object", "description": "List of spiders.", "required": [ "spiders", "total" ], "properties": { "spiders": { "type": "array", "items": { "$ref": "#/components/schemas/SpiderResponse" } }, "total": { "type": "integer", "format": "int64" } } }, "SpiderResponse": { "type": "object", "description": "Response for a spider definition.", "required": [ "id", "name", "kind", "version", "status", "definition", "handler_count", "field_count", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string", "format": "date-time" }, "definition": {}, "description": { "type": [ "string", "null" ] }, "field_count": { "type": "integer", "minimum": 0 }, "handler_count": { "type": "integer", "minimum": 0 }, "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "name": { "type": "string" }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpiderScopeDto" } ] }, "status": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "SpiderScopeDto": { "type": "object", "description": "Spider scope DTO.", "properties": { "allowed_patterns": { "type": "array", "items": { "type": "string" } }, "denied_patterns": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "max_depth": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "start_urls": { "type": "array", "items": { "type": "string" } } } }, "SslCheckRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string" } } }, "SslDto": { "type": "object", "required": [ "enabled", "valid" ], "properties": { "days_until_expiry": { "type": [ "integer", "null" ], "format": "int64" }, "enabled": { "type": "boolean" }, "issuer": { "type": [ "string", "null" ] }, "issues": { "type": "array", "items": { "type": "string" } }, "valid": { "type": "boolean" } } }, "StageMetrics": { "type": "object", "required": [ "stage", "count", "value_cents" ], "properties": { "count": { "type": "integer", "format": "int64" }, "stage": { "type": "string" }, "value_cents": { "type": "integer", "format": "int64" } } }, "StartScheduleRequest": { "type": "object", "description": "Request to start a pipeline schedule.", "properties": { "cron_expression": { "type": [ "string", "null" ] } } }, "StatsRequest": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } }, "StatsResponse": { "type": "object", "required": [ "path", "row_count", "file_count", "total_bytes" ], "properties": { "file_count": { "type": "integer", "format": "int64", "minimum": 0 }, "path": { "type": "string" }, "row_count": { "type": "integer", "format": "int64", "minimum": 0 }, "total_bytes": { "type": "integer", "format": "int64", "minimum": 0 } } }, "StealthConfigDto": { "type": "object", "description": "Stealth/proxy configuration DTO. All fields are optional — only specify\nwhat you want to override. Used for both site-level defaults and per-job overrides.", "properties": { "auto_escalate": { "type": [ "boolean", "null" ] }, "browser_headers": { "type": [ "boolean", "null" ] }, "custom_headers": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" } }, "delay_ms": { "type": [ "array", "null" ], "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "geo_country": { "type": [ "string", "null" ] }, "max_escalation_tier": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "proxy_tier": { "type": [ "string", "null" ] }, "rotate_user_agent": { "type": [ "boolean", "null" ] }, "rotation_strategy": { "type": [ "string", "null" ] }, "user_agent": { "type": [ "string", "null" ] } } }, "StepResultDto": { "type": "object", "description": "Result of a single pipeline step.", "required": [ "step_name", "status", "rows_in", "rows_out", "duration_ms" ], "properties": { "duration_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "error": { "type": [ "string", "null" ] }, "rows_in": { "type": "integer", "minimum": 0 }, "rows_out": { "type": "integer", "minimum": 0 }, "status": { "type": "string" }, "step_name": { "type": "string" } } }, "StrategyConfigDto": { "type": "object", "description": "User-configurable strategy parameters (API-facing DTO).", "required": [ "base_strategy" ], "properties": { "artifact_discovery": { "type": [ "boolean", "null" ] }, "base_strategy": { "type": "string" }, "depth_penalty": { "type": "number", "format": "double" }, "freshness_boost": { "type": "number", "format": "double" }, "keyword_targets": { "type": "array", "items": { "type": "string" } }, "max_depth": { "type": "integer", "format": "int32", "minimum": 0 }, "seed_topics": { "type": "array", "items": { "type": "string" } } } }, "StrategyListResponse": { "type": "object", "description": "List of strategies.", "required": [ "strategies" ], "properties": { "strategies": { "type": "array", "items": { "$ref": "#/components/schemas/StrategyResponse" } } } }, "StrategyResponse": { "type": "object", "description": "Response for a named strategy.", "required": [ "id", "name", "config", "created_at", "updated_at" ], "properties": { "config": { "$ref": "#/components/schemas/StrategyConfigDto" }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SubredditPost": { "type": "object", "required": [ "id", "title", "subreddit", "score", "num_comments", "created_utc" ], "properties": { "created_utc": { "type": "number", "format": "double" }, "id": { "type": "string" }, "num_comments": { "type": "integer", "format": "int64" }, "score": { "type": "integer", "format": "int64" }, "selftext": { "type": [ "string", "null" ] }, "subreddit": { "type": "string" }, "title": { "type": "string" }, "url": { "type": [ "string", "null" ] } } }, "SubredditPostsResponse": { "type": "object", "required": [ "posts" ], "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/SubredditPost" } } } }, "SuggestFieldsRequest": { "type": "object", "description": "Request to suggest extractable fields from a URL.", "required": [ "url" ], "properties": { "url": { "type": "string" } } }, "SuggestFieldsResponse": { "type": "object", "description": "Response for field suggestions.", "required": [ "url", "fields" ], "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/SuggestedFieldDto" } }, "url": { "type": "string" } } }, "SuggestedFieldDto": { "type": "object", "description": "A suggested field from AI analysis.", "required": [ "name", "selector", "confidence" ], "properties": { "alternatives": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "number", "format": "double" }, "name": { "type": "string" }, "rationale": { "type": [ "string", "null" ] }, "sample_value": { "type": [ "string", "null" ] }, "selector": { "type": "string" } } }, "SyntheticJobResponse": { "type": "object", "required": [ "id", "account_id", "operation", "model_endpoint", "status", "input_rows", "output_rows", "guardrail_violations", "created_at" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "guardrail_violations": {}, "id": { "type": "string", "format": "uuid" }, "input_rows": { "type": "integer", "format": "int64" }, "model_endpoint": {}, "operation": { "type": "string" }, "output_rows": { "type": "integer", "format": "int64" }, "pipeline_run_id": { "type": [ "string", "null" ], "format": "uuid" }, "status": { "type": "string" } } }, "TableCounts": { "type": "object", "required": [ "hospitals", "providers", "billing_codes", "payers", "plans", "hospital_rates", "insurer_rates", "data_sources", "pipeline_runs", "geo_reference" ], "properties": { "billing_codes": { "type": "integer", "format": "int64" }, "data_sources": { "type": "integer", "format": "int64" }, "geo_reference": { "type": "integer", "format": "int64" }, "hospital_rates": { "type": "integer", "format": "int64" }, "hospitals": { "type": "integer", "format": "int64" }, "insurer_rates": { "type": "integer", "format": "int64" }, "payers": { "type": "integer", "format": "int64" }, "pipeline_runs": { "type": "integer", "format": "int64" }, "plans": { "type": "integer", "format": "int64" }, "providers": { "type": "integer", "format": "int64" } } }, "TaxonomyCategoryDto": { "type": "object", "required": [ "name", "category", "children" ], "properties": { "category": { "type": "string" }, "children": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyNodeDto" } }, "name": { "type": "string" } } }, "TaxonomyNodeDto": { "type": "object", "required": [ "id", "name", "level", "keyword_count", "url_pattern_count" ], "properties": { "id": { "type": "string" }, "keyword_count": { "type": "integer", "minimum": 0 }, "level": { "type": "string" }, "name": { "type": "string" }, "url_pattern_count": { "type": "integer", "minimum": 0 } } }, "TaxonomyTreeResponse": { "type": "object", "required": [ "node_count", "categories" ], "properties": { "categories": { "type": "array", "items": { "$ref": "#/components/schemas/TaxonomyCategoryDto" } }, "node_count": { "type": "integer", "minimum": 0 } } }, "TelemetryDashboardResponse": { "type": "object", "required": [ "project_id", "total_events", "total_sessions", "unique_visitors", "error_count", "top_events", "daily_metrics" ], "properties": { "avg_session_duration_ms": { "type": [ "integer", "null" ], "format": "int64" }, "daily_metrics": { "type": "array", "items": { "$ref": "#/components/schemas/DailyMetricDto" } }, "error_count": { "type": "integer", "format": "int64" }, "project_id": { "type": "string", "format": "uuid" }, "top_events": { "type": "array", "items": { "$ref": "#/components/schemas/EventCountDto" } }, "total_events": { "type": "integer", "format": "int64" }, "total_sessions": { "type": "integer", "format": "int64" }, "unique_visitors": { "type": "integer", "format": "int64" } } }, "TemplateResponse": { "type": "object", "description": "Stored workflow template row as returned from the API.", "required": [ "id", "name", "version", "template", "status", "created_at", "updated_at" ], "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "description": { "type": [ "string", "null" ] }, "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "template": { "type": "object" }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "format": "int32" } } }, "TestSpiderRequest": { "type": "object", "description": "Request to test a spider against a URL.", "required": [ "url" ], "properties": { "handler_name": { "type": [ "string", "null" ] }, "url": { "type": "string" } } }, "TestSpiderResponse": { "type": "object", "description": "Result of testing a spider against a URL.", "required": [ "url", "fields_extracted", "extracted_data", "navigation_urls", "duration_ms", "warnings" ], "properties": { "duration_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "extracted_data": {}, "fields_extracted": { "type": "integer", "minimum": 0 }, "matched_handler": { "type": [ "string", "null" ] }, "navigation_urls": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "ThreadCommentsResponse": { "type": "object", "required": [ "comments" ], "properties": { "comments": { "type": "array", "items": { "$ref": "#/components/schemas/RedditComment" } } } }, "TimelineEvent": { "type": "object", "required": [ "event_type" ], "properties": { "counterpart_id": { "type": [ "string", "null" ], "description": "The other entity participating in the fact." }, "event_type": { "type": "string", "description": "Relation type of the underlying edge." }, "expired_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the fact was invalidated, if it no longer holds." }, "fact": { "type": [ "string", "null" ], "description": "Natural-language fact, when Graphiti extracted one." }, "timestamp": { "type": [ "string", "null" ], "format": "date-time", "description": "When the fact was established in the graph." } } }, "TimelineResponse": { "type": "object", "required": [ "entity", "entity_id", "name", "events", "source" ], "properties": { "entity": { "type": "string", "description": "The query string the entity was resolved from." }, "entity_id": { "type": "string", "description": "Resolved Graphiti entity id." }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" }, "description": "Events ordered oldest-first." }, "name": { "type": "string", "description": "Resolved entity display name." }, "source": { "type": "string", "description": "Backing store for the timeline." }, "summary": { "type": [ "string", "null" ] } } }, "TokenAccountQuery": { "type": "object", "properties": { "account_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Tenant account id. Defaults to the authenticated request account." } } }, "TraceResponse": { "type": "object", "required": [ "trace_id", "spans" ], "properties": { "spans": { "type": "array", "items": { "$ref": "#/components/schemas/SpanResponse" } }, "trace_id": { "type": "string" } } }, "TrendingIssue": { "type": "object", "required": [ "issue_type", "count", "trend", "affected_sites" ], "properties": { "affected_sites": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer", "format": "int64" }, "issue_type": { "type": "string" }, "trend": { "type": "string" } } }, "TriageRequest": { "type": "object", "description": "Request to triage an incident.", "properties": { "assigned_to": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] } } }, "TriggerBootstrapRequest": { "type": "object", "properties": { "max_rows": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "source_url": { "type": [ "string", "null" ] } } }, "TriggerCmsDiscoveryRequest": { "type": "object", "properties": { "force": { "type": [ "boolean", "null" ] } } }, "TriggerDiscoveryRequest": { "type": "object", "properties": { "seed_urls": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "TriggerHospitalMrfRequest": { "type": "object", "required": [ "source_url" ], "properties": { "hospital_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_url": { "type": "string" } } }, "TriggerPipelineResponse": { "type": "object", "required": [ "run_id", "status" ], "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } } }, "TriggerReferenceDataRequest": { "type": "object", "required": [ "source_type" ], "properties": { "source_type": { "type": "string" } } }, "TriggerTicIngestionRequest": { "type": "object", "required": [ "insurer_slug" ], "properties": { "data_source_id": { "type": [ "string", "null" ], "format": "uuid" }, "insurer_slug": { "type": "string" }, "max_files": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "UpdateAssetDefinitionRequest": { "type": "object", "properties": { "is_active": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "quality_gate": {}, "schedule_cron": { "type": [ "string", "null" ] }, "source_config": {} } }, "UpdateBriefRequest": { "type": "object", "properties": { "outline": {}, "status": { "type": [ "string", "null" ] }, "target_word_count": { "type": [ "integer", "null" ], "format": "int32" }, "title": { "type": [ "string", "null" ] } } }, "UpdateCompetitorsRequest": { "type": "object", "required": [ "site_id", "competitors" ], "properties": { "competitors": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitorEntry" } }, "site_id": { "type": "string", "format": "uuid" } } }, "UpdateDatasetRequest": { "type": "object", "description": "Request to update a dataset.", "properties": { "columns": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/DatasetColumnDto" } }, "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "UpdateDealRequest": { "type": "object", "properties": { "close_date": { "type": [ "string", "null" ], "format": "date" }, "probability": { "type": [ "number", "null" ], "format": "double" }, "stage": { "type": [ "string", "null" ] }, "value_cents": { "type": [ "integer", "null" ], "format": "int64" } } }, "UpdateDestinationRequest": { "type": "object", "properties": { "config": {}, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] }, "signal_types": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "UpdateDocumentRequest": { "type": "object", "description": "Request to update a content document.", "properties": { "content_json": {}, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time" }, "slug": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "target_keywords": { "type": [ "array", "null" ], "items": { "type": "string" } }, "title": { "type": [ "string", "null" ] } } }, "UpdateEtlProgressRequest": { "type": "object", "description": "Request to update ETL run progress (from Restate workflow)", "required": [ "step_index", "step_name", "status", "bytes_processed", "rows_processed" ], "properties": { "bytes_processed": { "type": "integer", "format": "int64", "minimum": 0 }, "rows_processed": { "type": "integer", "format": "int64", "minimum": 0 }, "status": { "type": "string" }, "step_index": { "type": "integer", "format": "int32" }, "step_name": { "type": "string" } } }, "UpdateEtlStatusRequest": { "type": "object", "description": "Request to update ETL run final status (from Restate workflow)", "required": [ "status" ], "properties": { "error": { "type": [ "string", "null" ] }, "status": { "type": "string" } } }, "UpdateIncidentRequest": { "type": "object", "description": "Request to update an incident.", "properties": { "root_cause": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } } }, "UpdateMonitorRequest": { "type": "object", "properties": { "authors": { "type": [ "array", "null" ], "items": { "type": "string" } }, "companies": { "type": [ "array", "null" ], "items": { "type": "string" } }, "enabled": { "type": [ "boolean", "null" ] }, "industries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "keywords": { "type": [ "array", "null" ], "items": { "type": "string" } }, "monitor_type": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "priority": { "type": [ "string", "null" ] }, "seniority_filter": { "type": [ "array", "null" ], "items": { "type": "string" } }, "stealth_config": {} } }, "UpdatePipelineRequest": { "type": "object", "description": "Request to update an enrichment pipeline.", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "schedule": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "steps": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PipelineStepDto" } } } }, "UpdateProfileRequest": { "type": "object", "required": [ "site_id" ], "properties": { "industry": { "type": [ "string", "null" ] }, "products": { "type": [ "array", "null" ], "items": { "type": "string" } }, "site_id": { "type": "string", "format": "uuid" }, "social_profiles": {}, "target_audience": { "type": [ "string", "null" ] } } }, "UpdateProjectRequest": { "type": "object", "properties": { "allowed_origins": { "type": [ "array", "null" ], "items": { "type": "string" } }, "config": {}, "enabled": { "type": [ "boolean", "null" ] }, "name": { "type": [ "string", "null" ] } } }, "UpdateRowRequest": { "type": "object", "description": "Request to update a row.", "required": [ "data" ], "properties": { "data": {} } }, "UpdateRunProgressRequest": { "type": "object", "description": "Request to update pipeline run progress.", "required": [ "step_results", "rows_processed" ], "properties": { "rows_processed": { "type": "integer", "minimum": 0 }, "step_results": { "type": "array", "items": { "$ref": "#/components/schemas/StepResultDto" } } } }, "UpdateRunStatusRequest": { "type": "object", "description": "Request to update pipeline run status.", "required": [ "status" ], "properties": { "error": { "type": [ "string", "null" ] }, "status": { "type": "string" } } }, "UpdateScheduledAuditRequest": { "type": "object", "properties": { "enabled": { "type": [ "boolean", "null" ] }, "frequency": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AuditScheduleFrequency" } ] }, "max_pages": { "type": [ "integer", "null" ], "format": "int32" } } }, "UpdateSettingsRequest": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "type": "array", "items": { "$ref": "#/components/schemas/SettingUpdate" } } } }, "UpdateSiteRequest": { "type": "object", "required": [ "site_id" ], "properties": { "framework": { "type": [ "string", "null" ] }, "gsc_property": { "type": [ "string", "null" ] }, "site_id": { "type": "string", "format": "uuid" }, "stealth_config": { "description": "Site-level stealth/proxy configuration defaults" } } }, "UpdateSpiderRequest": { "type": "object", "description": "Request to update a spider definition.", "properties": { "definition": {}, "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "scope": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SpiderScopeDto" } ] }, "status": { "type": [ "string", "null" ] } } }, "UpdateTemplateRequest": { "type": "object", "description": "Request body for updating a workflow template.", "required": [ "template" ], "properties": { "template": { "type": "object", "description": "Updated template. Version will be bumped automatically." } } }, "UpdateWeightsRequest": { "type": "object", "required": [ "weights" ], "properties": { "thresholds": {}, "weights": {} } }, "UpdateWhiteLabelRequest": { "type": "object", "properties": { "brand_color": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "custom_domain": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "remove_branding": { "type": [ "boolean", "null" ] } } }, "UsageBucket": { "type": "object", "required": [ "day", "endpoint_group", "is_test", "request_count" ], "properties": { "api_key_id": { "type": [ "string", "null" ], "format": "uuid", "description": "`api_keys.id`; null for session (JWT) traffic." }, "day": { "type": "string", "format": "date", "description": "UTC day bucket." }, "endpoint_group": { "type": "string", "description": "First path segment after /api/v1 (e.g. `crawl`, `social`)." }, "is_test": { "type": "boolean", "description": "Whether the credential was a ck_test_ sandbox key." }, "key_name": { "type": [ "string", "null" ], "description": "Display name of the key, if it still exists." }, "key_prefix": { "type": [ "string", "null" ], "description": "Key prefix (e.g. `ck_live_abc1`), if the key still exists." }, "request_count": { "type": "integer", "format": "int64" } } }, "UsageResponse": { "type": "object", "required": [ "from", "to", "total_requests", "buckets" ], "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/UsageBucket" } }, "from": { "type": "string", "format": "date" }, "to": { "type": "string", "format": "date" }, "total_requests": { "type": "integer", "format": "int64" } } }, "UsageSummary": { "type": "object", "required": [ "checks_today", "checks_limit", "audits_this_week", "audits_limit" ], "properties": { "audits_limit": { "type": "integer", "format": "int32" }, "audits_this_week": { "type": "integer", "format": "int32" }, "checks_limit": { "type": "integer", "format": "int32" }, "checks_today": { "type": "integer", "format": "int32" } } }, "ValidateRequest": { "type": "object", "required": [ "api_key" ], "properties": { "api_key": { "type": "string" } } }, "ValidateResponse": { "type": "object", "required": [ "valid", "account_id", "tier", "scopes", "usage" ], "properties": { "account_id": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string" } }, "tier": { "type": "string" }, "usage": { "$ref": "#/components/schemas/UsageSummary" }, "valid": { "type": "boolean" } } }, "ValidateSchemaRequest": { "type": "object", "required": [ "schema_name", "data" ], "properties": { "data": {}, "schema_name": { "type": "string" } } }, "ValidateTemplateRequest": { "type": "object", "description": "Request body for template validation.", "required": [ "template" ], "properties": { "template": { "type": "object", "description": "The template to validate (not stored)." } } }, "ValidationResponse": { "type": "object", "description": "Validation result.", "required": [ "valid", "errors", "warnings" ], "properties": { "errors": { "type": "array", "items": { "type": "string" } }, "valid": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "VerifyKeyQuery": { "type": "object", "description": "Query params for key verification", "required": [ "site_id" ], "properties": { "site_id": { "type": "string", "format": "uuid" } } }, "VerifyKeyResponse": { "type": "object", "description": "Response from key verification", "required": [ "key", "key_file_url", "accessible" ], "properties": { "accessible": { "type": "boolean" }, "key": { "type": "string" }, "key_file_url": { "type": "string" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "VerifyRequest": { "type": "object", "required": [ "job_id", "verification_type" ], "properties": { "config": {}, "job_id": { "type": "string", "format": "uuid" }, "verification_type": { "type": "string" } } }, "VerifyResponse": { "type": "object", "required": [ "job_id", "passed", "total_checked", "passed_count", "failed_count", "details" ], "properties": { "details": {}, "failed_count": { "type": "integer", "format": "int64" }, "job_id": { "type": "string", "format": "uuid" }, "passed": { "type": "boolean" }, "passed_count": { "type": "integer", "format": "int64" }, "total_checked": { "type": "integer", "format": "int64" } } }, "WhiteLabelDto": { "type": "object", "required": [ "remove_branding" ], "properties": { "brand_color": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "custom_domain": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "remove_branding": { "type": "boolean" } } }, "WhiteLabelResponse": { "type": "object", "required": [ "settings" ], "properties": { "settings": { "$ref": "#/components/schemas/WhiteLabelDto" } } } }, "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT or API Key", "description": "Session JWT token or CrawlKit API key (ck_live_*)" } } }, "tags": [ { "name": "Alerts", "description": "Alert management — notifications, settings, Graphiti-powered insights" }, { "name": "Clients", "description": "Agency client management — clients, white-label, custom domains (Agency tier)" }, { "name": "Health", "description": "Service health checks" }, { "name": "Search", "description": "Web/document search over the unified vector index with honest provenance labels" }, { "name": "Auth", "description": "API key validation and usage tracking" }, { "name": "GSC", "description": "Google Search Console — OAuth, URL inspection, analytics, indexing" }, { "name": "Analysis", "description": "SEO analysis — content checking, URL auditing, site health reports" }, { "name": "DNS", "description": "DNS auditing — SSL, redirects, email authentication, record validation" }, { "name": "Profile", "description": "Business profile generation and management" }, { "name": "Keywords", "description": "Keyword management — GSC import, CSV import, recommendations" }, { "name": "Landscape", "description": "Competitive landscape analysis (Pro tier)" }, { "name": "Content", "description": "Content tools — briefs, JSON-LD, internal links, SERP analysis (Pro tier)" }, { "name": "Feedback", "description": "Feedback loops — issue detection, fix tracking, verification" }, { "name": "IndexNow", "description": "IndexNow protocol — instant notification to Bing, Yandex, Naver, Seznam" }, { "name": "Sites", "description": "Site management — CRUD operations for tracked domains" }, { "name": "Dashboard", "description": "Dashboard overview — aggregated account metrics" }, { "name": "Audit", "description": "Real-time site audit via Server-Sent Events" }, { "name": "Datasets", "description": "Dataset management — create, populate, import/export typed datasets for enrichment" }, { "name": "Spiders", "description": "Spider management — declarative web scraping configs with AI-generated extractors" }, { "name": "Enrichment", "description": "Data enrichment — pluggable enrichment sources, batch processing, transparent pipelines" }, { "name": "Inspection", "description": "URL inspection — lightweight HTTP/browser inspection, HTML analysis, selector discovery" }, { "name": "Pipelines", "description": "Pipeline orchestration — DAG-based data processing with crawl, enrich, transform, export steps" }, { "name": "Queue", "description": "Queue management — priority queue for crawl jobs with retry and batch operations" }, { "name": "Crawl", "description": "Crawl jobs — distributed crawling with strategies, frontier management, proxy rotation" }, { "name": "Content Workspace", "description": "Content workspace — AI-powered document creation, editing, publishing, editorial calendar" }, { "name": "Intelligence", "description": "Intelligence — causal analysis, Monte Carlo simulation, forecasting, knowledge graph queries" }, { "name": "Leads", "description": "Lead intelligence — lead scoring, signal tracking, campaign management, qualification" }, { "name": "Pipeline Deals", "description": "Revenue pipeline — deal management, attribution tracking, revenue forecasting" }, { "name": "Scoring", "description": "Scoring models for opportunity, quality, trust, lead fit, and operational decision support" }, { "name": "Measurement", "description": "Measurement — closed-loop experiment tracking, observations, attributions, calibration, and dashboard" }, { "name": "Social Reddit", "description": "Reddit monitoring — keyword/brand mention tracking with sentiment analysis" }, { "name": "Social LinkedIn", "description": "LinkedIn monitoring — professional network monitoring with seniority and industry filtering" }, { "name": "Social - Channels", "description": "Platform-generic social channel profiles (subreddits, LinkedIn company pages)" }, { "name": "Usage", "description": "Per-key API usage metering — request counts by key, endpoint group and day" }, { "name": "Graph", "description": "Temporal knowledge graph — entity timelines from the Graphiti sidecar" }, { "name": "Telemetry", "description": "Telemetry — analytics ingestion, sessions, traces, errors, metrics, funnel analysis, and dashboard" }, { "name": "Artifacts", "description": "Artifacts — register, list, download, and sign data assets and generated outputs" }, { "name": "Asset Definitions", "description": "Asset definitions — reusable metadata definitions for data products, workflows, and governed assets" }, { "name": "Lineage", "description": "Lineage — asset graph, upstream/downstream provenance, consent, and crawl/data lineage" }, { "name": "Observatory", "description": "Observatory — dataset profiling, anomaly detection, and profile comparison" }, { "name": "ETL", "description": "ETL — parse JSON/CSV, write Parquet, load tables, compress artifacts, fetch remote files, and run ETL pipelines" }, { "name": "Query", "description": "Query — DuckDB, DuckDB hybrid, DataFusion, Arrow-native SQL, Parquet views/tables, schema introspection, and exports" }, { "name": "SchemaRegistry", "description": "Schema registry — versioned JSON schemas and validation for datasets, artifacts, and workflow contracts" }, { "name": "ScheduledAudits", "description": "Scheduled audits — recurring audit definitions and lifecycle management" }, { "name": "SEO Reports", "description": "SEO reports — generated report listing and retrieval" }, { "name": "Cost Attribution", "description": "Cost attribution — cost records, summaries, and usage accounting for data/AI workflows" }, { "name": "Healing", "description": "Self-healing — diagnostics, patch proposals, patch application, rollback, and auto-heal orchestration" }, { "name": "Governance", "description": "Governance — policy review, comments, approval queues, and managed workflow policy state" }, { "name": "Incidents", "description": "Incidents — incident creation, triage, resolution, and timeline events" }, { "name": "Synthetic", "description": "Synthetic data — generation, verification, guardrails, and operation discovery" }, { "name": "Workflow Templates", "description": "Workflow templates — reusable durable workflows, validation, operation discovery, runs, monitoring, and cancellation" }, { "name": "OpenRate", "description": "OpenRate — healthcare price-transparency search, comparison, discrepancy detection, and pipeline status" }, { "name": "OpenRate Admin", "description": "OpenRate admin — source registry, MRF/TiC ingestion, CMS discovery, schedules, reference imports, and view refreshes" }, { "name": "Quality", "description": "Data quality — structured quality gates, heuristic filters, deduplication, scoring, classification, decontamination" } ] }