{ "openapi": "3.1.0", "info": { "title": "SPECTRA Developer API", "version": "1.1.0-rc.3", "description": "Read-only tenant-bound access to approved stored monitors, content, analytics and shared reports. API access does not activate collection, publishing or paid analysis." }, "servers": [ { "url": "https://api.spectra-ai.app", "description": "Production API; backend-only machine authentication" } ], "x-external-api-base-url": "https://api.spectra-ai.app/api/external/v1", "paths": { "/api/external/v1/status": { "get": { "operationId": "externalStatus", "summary": "Read /status", "description": "Required machine scope: status.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "status.read", "parameters": [], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalStatus" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/monitors": { "get": { "operationId": "externalMonitors", "summary": "Read /monitors", "description": "Required machine scope: monitors.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "monitors.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." }, { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Owned monitor UUID; restrict evidence to unsuppressed matches. Foreign identifiers return an empty list." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Alias for monitorId. If both are supplied they must match." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "X", "Facebook", "Instagram", "YouTube", "Rss", "Manual" ] }, "description": "One provider name, case-insensitive; selection does not enable collection." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Literal substring, maximum 100 characters. Monitors/topics search name; content/analytics search safe external IDs and RSS titles only." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "Monitor state, case-insensitive.", "enum": [ "Draft", "Scheduled", "Active", "Paused", "Completed", "Failed", "Stopped", "Archived" ] }, "description": "Stored state. Monitor values are case-insensitive; reports match stored state exactly." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalMonitorPage" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/monitors/{id}": { "get": { "operationId": "externalMonitorsId", "summary": "Read /monitors/{id}", "description": "Required machine scope: monitors.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "monitors.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Owned record UUID returned by the corresponding list; inaccessible, absent or expired records return 404." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalMonitor" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Absent, expired or inaccessible resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/topics": { "get": { "operationId": "externalTopics", "summary": "Read /topics", "description": "Required machine scope: monitors.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "monitors.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Literal substring, maximum 100 characters. Monitors/topics search name; content/analytics search safe external IDs and RSS titles only." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalTopicPage" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/countries": { "get": { "operationId": "externalCountries", "summary": "Read /countries", "description": "Required machine scope: analytics.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "analytics.read", "parameters": [], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalCountry" } } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/content": { "get": { "operationId": "externalContent", "summary": "Read /content", "description": "Required machine scope: content.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "content.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." }, { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Owned monitor UUID; restrict evidence to unsuppressed matches. Foreign identifiers return an empty list." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Alias for monitorId. If both are supplied they must match." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "X", "Facebook", "Instagram", "YouTube", "Rss", "Manual" ] }, "description": "One provider name, case-insensitive; selection does not enable collection." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1100 }, "description": "Assigned ISO2 codes separated by commas with OR semantics and deduplication; case-insensitive. unknown matches no recorded geography for the selected role (excludes policy-withheld evidence). Omit or use global alone for no geography restriction. Global cannot be combined with country codes." }, { "name": "geographyRole", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "subject", "origin", "source" ], "default": "subject" }, "description": "Evidence role: subject (default), origin or source. No claim of residence, nationality or identity." }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "unclear", "not_analyzed", "failed", "uncertain" ] }, "description": "One available sentiment state/label; excludes policy-withheld metrics." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive publication time (collection fallback). Default to minus 7 days; explicit offset required. Maximum interval 31 days." }, "description": "Inclusive publication time with collection-time fallback. Explicit ISO8601 offset required. Defaults to seven days before to; maximum interval 31 days." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Exclusive end, default asOfUtc; must not exceed asOfUtc." }, "description": "Exclusive end, default asOfUtc. Must be greater than from and no later than asOfUtc." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Literal substring, maximum 100 characters. Monitors/topics search name; content/analytics search safe external IDs and RSS titles only." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 35 }, "description": "Exact case-insensitive language tag, for example en, fr or en-GB; independent of geography. en does not match en-GB. Missing language never matches. No translation or identity inference." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalContentPage" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/content/{id}": { "get": { "operationId": "externalContentId", "summary": "Read /content/{id}", "description": "Required machine scope: content.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "content.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Owned record UUID returned by the corresponding list; inaccessible, absent or expired records return 404." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalContent" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Absent, expired or inaccessible resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/analytics/summary": { "get": { "operationId": "externalAnalyticsSummary", "summary": "Read /analytics/summary", "description": "Required machine scope: analytics.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "analytics.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000. Validated only; analytics aggregates are not paginated." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100. Validated only; analytics aggregates are not paginated." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." }, { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Owned monitor UUID; restrict evidence to unsuppressed matches. Foreign identifiers return an empty list." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Alias for monitorId. If both are supplied they must match." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "X", "Facebook", "Instagram", "YouTube", "Rss", "Manual" ] }, "description": "One provider name, case-insensitive; selection does not enable collection." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1100 }, "description": "Assigned ISO2 codes separated by commas with OR semantics and deduplication; case-insensitive. unknown matches no recorded geography for the selected role (excludes policy-withheld evidence). Omit or use global alone for no geography restriction. Global cannot be combined with country codes." }, { "name": "geographyRole", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "subject", "origin", "source" ], "default": "subject" }, "description": "Evidence role: subject (default), origin or source. No claim of residence, nationality or identity." }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "unclear", "not_analyzed", "failed", "uncertain" ] }, "description": "One available sentiment state/label; excludes policy-withheld metrics." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive publication time (collection fallback). Default to minus 7 days; explicit offset required. Maximum interval 31 days." }, "description": "Inclusive publication time with collection-time fallback. Explicit ISO8601 offset required. Defaults to seven days before to; maximum interval 31 days." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Exclusive end, default asOfUtc; must not exceed asOfUtc." }, "description": "Exclusive end, default asOfUtc. Must be greater than from and no later than asOfUtc." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Literal substring, maximum 100 characters. Monitors/topics search name; content/analytics search safe external IDs and RSS titles only." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 35 }, "description": "Exact case-insensitive language tag, for example en, fr or en-GB; independent of geography. en does not match en-GB. Missing language never matches. No translation or identity inference." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAnalytics" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/analytics/sentiment": { "get": { "operationId": "externalAnalyticsSentiment", "summary": "Read /analytics/sentiment", "description": "Required machine scope: analytics.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "analytics.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000. Validated only; analytics aggregates are not paginated." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100. Validated only; analytics aggregates are not paginated." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." }, { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Owned monitor UUID; restrict evidence to unsuppressed matches. Foreign identifiers return an empty list." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Alias for monitorId. If both are supplied they must match." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "X", "Facebook", "Instagram", "YouTube", "Rss", "Manual" ] }, "description": "One provider name, case-insensitive; selection does not enable collection." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1100 }, "description": "Assigned ISO2 codes separated by commas with OR semantics and deduplication; case-insensitive. unknown matches no recorded geography for the selected role (excludes policy-withheld evidence). Omit or use global alone for no geography restriction. Global cannot be combined with country codes." }, { "name": "geographyRole", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "subject", "origin", "source" ], "default": "subject" }, "description": "Evidence role: subject (default), origin or source. No claim of residence, nationality or identity." }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "unclear", "not_analyzed", "failed", "uncertain" ] }, "description": "One available sentiment state/label; excludes policy-withheld metrics." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive publication time (collection fallback). Default to minus 7 days; explicit offset required. Maximum interval 31 days." }, "description": "Inclusive publication time with collection-time fallback. Explicit ISO8601 offset required. Defaults to seven days before to; maximum interval 31 days." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Exclusive end, default asOfUtc; must not exceed asOfUtc." }, "description": "Exclusive end, default asOfUtc. Must be greater than from and no later than asOfUtc." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Literal substring, maximum 100 characters. Monitors/topics search name; content/analytics search safe external IDs and RSS titles only." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 35 }, "description": "Exact case-insensitive language tag, for example en, fr or en-GB; independent of geography. en does not match en-GB. Missing language never matches. No translation or identity inference." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAnalytics" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/analytics/countries": { "get": { "operationId": "externalAnalyticsCountries", "summary": "Read /analytics/countries", "description": "Required machine scope: analytics.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "analytics.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000. Validated only; analytics aggregates are not paginated." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100. Validated only; analytics aggregates are not paginated." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." }, { "name": "monitorId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Owned monitor UUID; restrict evidence to unsuppressed matches. Foreign identifiers return an empty list." }, { "name": "topicId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Alias for monitorId. If both are supplied they must match." }, { "name": "provider", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "X", "Facebook", "Instagram", "YouTube", "Rss", "Manual" ] }, "description": "One provider name, case-insensitive; selection does not enable collection." }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 1100 }, "description": "Assigned ISO2 codes separated by commas with OR semantics and deduplication; case-insensitive. unknown matches no recorded geography for the selected role (excludes policy-withheld evidence). Omit or use global alone for no geography restriction. Global cannot be combined with country codes." }, { "name": "geographyRole", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "subject", "origin", "source" ], "default": "subject" }, "description": "Evidence role: subject (default), origin or source. No claim of residence, nationality or identity." }, { "name": "sentiment", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "positive", "negative", "neutral", "mixed", "unclear", "not_analyzed", "failed", "uncertain" ] }, "description": "One available sentiment state/label; excludes policy-withheld metrics." }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Inclusive publication time (collection fallback). Default to minus 7 days; explicit offset required. Maximum interval 31 days." }, "description": "Inclusive publication time with collection-time fallback. Explicit ISO8601 offset required. Defaults to seven days before to; maximum interval 31 days." }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Exclusive end, default asOfUtc; must not exceed asOfUtc." }, "description": "Exclusive end, default asOfUtc. Must be greater than from and no later than asOfUtc." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 100 }, "description": "Literal substring, maximum 100 characters. Monitors/topics search name; content/analytics search safe external IDs and RSS titles only." }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 35 }, "description": "Exact case-insensitive language tag, for example en, fr or en-GB; independent of geography. en does not match en-GB. Missing language never matches. No translation or identity inference." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalAnalytics" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/reports": { "get": { "operationId": "externalReports", "summary": "Read /reports", "description": "Required machine scope: reports.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "reports.read", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 }, "description": "One-based page number; default 1, maximum 100000." }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "description": "Items per page; default 25, maximum 100." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Stored state. Monitor values are case-insensitive; reports match stored state exactly." }, { "name": "asOfUtc", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Default now. Carry unchanged between list pages; stabilises additions, not privacy deletions or policy changes." }, "description": "Explicit ISO8601 timestamp with offset, default now. Carry unchanged between pages; stabilizes additions but not deletions/policy changes." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReportSummaryPage" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/reports/{id}": { "get": { "operationId": "externalReportsId", "summary": "Read /reports/{id}", "description": "Required machine scope: reports.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "reports.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Owned record UUID returned by the corresponding list; inaccessible, absent or expired records return 404." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReportDetail" } } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Absent, expired or inaccessible resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/external/v1/reports/{id}/download": { "get": { "operationId": "externalReportsIdDownload", "summary": "Read /reports/{id}/download", "description": "Required machine scope: reports.read. Tenant scope is fixed by the credential; no tenant selector is accepted.", "security": [ { "machineBearer": [] } ], "x-required-scope": "reports.read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Owned record UUID returned by the corresponding list; inaccessible, absent or expired records return 404." }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ], "default": "json" }, "description": "json (default) for the report envelope, or csv for aggregate rows. Case-sensitive." } ], "responses": { "200": { "description": "Authorised stored result; no collection, paid analysis or publication is triggered.", "headers": { "X-Request-Id": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalReportDetail" } }, "text/csv": { "schema": { "type": "string" }, "description": "Reviewed aggregate CSV export; same tenant/scope/expiry checks." } } }, "400": { "description": "Invalid filters or caller-selected tenant.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Invalid, expired or revoked machine credential.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope or access_denied after live approval/tenant recheck.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Absent, expired or inaccessible resource.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "405": { "description": "External API is read-only.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "report_unavailable: metadata is visible but results are unavailable. Includes state.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited; respect Retry-After.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "temporarily_unavailable for handled database or service-state failure. Other unexpected server failures do not guarantee a Problem body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "securitySchemes": { "machineBearer": { "type": "http", "scheme": "bearer", "bearerFormat": "spx_.", "description": "Revocable server-bound tenant machine credential; keep in the DDM backend." } }, "schemas": { "ExternalCollectionRun": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "state": { "type": "string" }, "startedAtUtc": { "type": "string", "format": "date-time" }, "completedAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "returnedOccurrences": { "type": "integer", "format": "int32" }, "newRecords": { "type": "integer", "format": "int32" }, "duplicates": { "type": "integer", "format": "int32" }, "errors": { "type": "integer", "format": "int32" }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "provider", "state", "startedAtUtc", "returnedOccurrences", "newRecords", "duplicates", "errors" ] }, "ExternalMonitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "geographicScope": { "type": "string", "description": "Anywhere means Global/unrestricted. TargetLocationsOnly and AnywhereMentioningTargetLocations use saved targets." }, "intendedCountries": { "type": "array", "items": { "type": "string" }, "description": "Distinct sorted country codes derived from available saved target references. Does not guarantee provider coverage." }, "collectionIntervalSeconds": { "anyOf": [ { "type": "integer", "format": "int32" }, { "type": "null" } ] }, "startsAtUtc": { "type": "string", "format": "date-time" }, "endsAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "continuous": { "type": "boolean" }, "lastSuccessfulCollectionAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastRun": { "anyOf": [ { "$ref": "#/components/schemas/ExternalCollectionRun" }, { "type": "null" } ] }, "storedEvidenceCount": { "type": "integer", "format": "int32" }, "stale": { "type": "boolean" }, "geographyTargets": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalMonitorGeography" }, "description": "Saved target IDs and labels, including country, region and city. Unavailable references retain ID with available=false and null metadata. ParentId links hierarchy, not necessarily another selected target." }, "languages": { "type": "array", "items": { "type": "string" }, "description": "Saved language preferences; empty means no language restriction." }, "geographyBasis": { "type": "string", "description": "Saved basis: subject, provider, source or legacy (default for old configurations). Provider basis corresponds to origin evidence; legacy follows the saved geographicScope." }, "timeZone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Saved IANA timezone preference; null for legacy configurations. startsAtUtc and endsAtUtc remain UTC instants." } }, "required": [ "id", "name", "state", "sources", "geographicScope", "intendedCountries", "startsAtUtc", "continuous", "storedEvidenceCount", "stale" ] }, "ExternalMonitorGeography": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "countryIsoCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "adminLevel": { "anyOf": [ { "type": "integer", "format": "int32" }, { "type": "null" } ] }, "parentId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "available": { "type": "boolean" } }, "required": [ "id", "available" ] }, "ExternalTopic": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "keywords": { "type": "array", "items": { "type": "string" } }, "phrases": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "keywords", "phrases", "exclusions", "sources" ] }, "ExternalSentiment": { "type": "object", "properties": { "state": { "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "analyzedAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "method": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "analyzerVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "score": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "uncertainty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidenceMeaning": { "type": "string" } }, "required": [ "state", "confidenceMeaning" ] }, "ExternalContentGeography": { "type": "object", "properties": { "countryIsoCode": { "type": "string" }, "countryName": { "type": "string" }, "role": { "type": "string" }, "provenance": { "type": "string" }, "resolutionAdminLevel": { "type": "integer", "format": "int32" }, "uncertainty": { "type": "string" }, "confidence": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "countryIsoCode", "countryName", "role", "provenance", "resolutionAdminLevel", "uncertainty" ] }, "ExternalContent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "collectedAtUtc": { "type": "string", "format": "date-time" }, "sentiment": { "$ref": "#/components/schemas/ExternalSentiment" }, "geography": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalContentGeography" } }, "monitorIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "redistributionMode": { "type": "string" }, "fullTextAvailable": { "type": "boolean" }, "geographyState": { "type": "string" } }, "required": [ "id", "provider", "collectedAtUtc", "sentiment", "geography", "monitorIds", "redistributionMode", "fullTextAvailable", "geographyState" ] }, "ExternalCountry": { "type": "object", "properties": { "countryIsoCode": { "type": "string" }, "name": { "type": "string" }, "coverageState": { "type": "string" }, "providerCountryFilter": { "type": "string" } }, "required": [ "countryIsoCode", "name", "coverageState", "providerCountryFilter" ] }, "ExternalCount": { "type": "object", "properties": { "key": { "type": "string" }, "count": { "type": "integer", "format": "int32" } }, "required": [ "key", "count" ] }, "ExternalCountryCount": { "type": "object", "properties": { "countryIsoCode": { "type": "string" }, "name": { "type": "string" }, "evidenceCount": { "type": "integer", "format": "int32" }, "geographyRole": { "type": "string" }, "provenance": { "type": "array", "items": { "type": "string" } } }, "required": [ "countryIsoCode", "name", "evidenceCount", "geographyRole", "provenance" ] }, "ExternalTrend": { "type": "object", "properties": { "dateUtc": { "type": "string" }, "evidenceCount": { "type": "integer", "format": "int32" }, "positive": { "type": "integer", "format": "int32" }, "negative": { "type": "integer", "format": "int32" }, "neutral": { "type": "integer", "format": "int32" }, "mixed": { "type": "integer", "format": "int32" }, "unclear": { "type": "integer", "format": "int32" }, "notAnalyzed": { "type": "integer", "format": "int32" }, "failed": { "type": "integer", "format": "int32" }, "uncertain": { "type": "integer", "format": "int32" }, "withheld": { "type": "integer", "format": "int32" } }, "required": [ "dateUtc", "evidenceCount", "positive", "negative", "neutral", "mixed", "unclear", "notAnalyzed", "failed", "uncertain", "withheld" ] }, "ExternalSourceCoverage": { "type": "object", "properties": { "provider": { "type": "string" }, "collectionVerified": { "type": "boolean" }, "storedEvidenceCount": { "type": "integer", "format": "int32" }, "successfulRuns": { "type": "integer", "format": "int32" }, "failedRuns": { "type": "integer", "format": "int32" }, "lastSuccessfulCollectionAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "state": { "type": "string" }, "storedContentCoverage": { "type": "boolean" } }, "required": [ "provider", "collectionVerified", "storedEvidenceCount", "successfulRuns", "failedRuns", "state", "storedContentCoverage" ] }, "ExternalAnalytics": { "type": "object", "properties": { "generatedAtUtc": { "type": "string", "format": "date-time" }, "asOfUtc": { "type": "string", "format": "date-time" }, "fromUtc": { "type": "string", "format": "date-time" }, "toUtc": { "type": "string", "format": "date-time" }, "dateBasis": { "type": "string" }, "totalEvidenceCount": { "type": "integer", "format": "int32" }, "sampleSize": { "type": "integer", "format": "int32" }, "truncated": { "type": "boolean" }, "sentiment": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalCount" } }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalCountryCount" } }, "unknownLocationCount": { "type": "integer", "format": "int32" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalCount" } }, "trends": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalTrend" } }, "sourceCoverage": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalSourceCoverage" } }, "evidenceReferences": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalSourceReference" } }, "limitations": { "type": "array", "items": { "type": "string" } }, "evidenceFingerprint": { "type": "string" }, "withheldLocationCount": { "type": "integer", "format": "int32" } }, "required": [ "generatedAtUtc", "asOfUtc", "fromUtc", "toUtc", "dateBasis", "totalEvidenceCount", "sampleSize", "truncated", "sentiment", "countries", "unknownLocationCount", "sources", "trends", "sourceCoverage", "evidenceReferences", "limitations", "evidenceFingerprint", "withheldLocationCount" ] }, "ExternalSourceReference": { "type": "object", "properties": { "contentId": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "externalId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "contentId", "provider" ] }, "ExternalStatus": { "type": "object", "properties": { "schemaVersion": { "type": "string" }, "observedAtUtc": { "type": "string", "format": "date-time" }, "activeMonitors": { "type": "integer", "format": "int32" }, "maximumActiveMonitors": { "type": "integer", "format": "int32" }, "storedEvidenceCount": { "type": "integer", "format": "int32" }, "collectionState": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalSourceCoverage" } }, "alerts": { "type": "array", "items": { "type": "string" } }, "paidAnalysisTriggered": { "type": "boolean" } }, "required": [ "schemaVersion", "observedAtUtc", "activeMonitors", "maximumActiveMonitors", "storedEvidenceCount", "collectionState", "sources", "alerts", "paidAnalysisTriggered" ] }, "ExternalReportSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "state": { "type": "string" }, "requestedAtUtc": { "type": "string", "format": "date-time" }, "generatedAtUtc": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAtUtc": { "type": "string", "format": "date-time" }, "snapshotSha256": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "title", "state", "requestedAtUtc", "expiresAtUtc" ] }, "ExternalReportDetail": { "type": "object", "properties": { "report": { "$ref": "#/components/schemas/ExternalReportSummary" }, "results": { "anyOf": [ { "$ref": "#/components/schemas/ExternalAnalytics" }, { "type": "null" } ] }, "schemaVersion": { "type": "string" } }, "required": [ "report", "schemaVersion" ] }, "ExternalMonitorPage": { "type": "object", "required": [ "items", "page", "pageSize", "totalCount", "hasMore", "asOfUtc", "requestId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalMonitor" } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "asOfUtc": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" } } }, "ExternalTopicPage": { "type": "object", "required": [ "items", "page", "pageSize", "totalCount", "hasMore", "asOfUtc", "requestId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalTopic" } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "asOfUtc": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" } } }, "ExternalContentPage": { "type": "object", "required": [ "items", "page", "pageSize", "totalCount", "hasMore", "asOfUtc", "requestId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalContent" } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "asOfUtc": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" } } }, "ExternalReportSummaryPage": { "type": "object", "required": [ "items", "page", "pageSize", "totalCount", "hasMore", "asOfUtc", "requestId" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExternalReportSummary" } }, "page": { "type": "integer", "minimum": 1 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "totalCount": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "asOfUtc": { "type": "string", "format": "date-time" }, "requestId": { "type": "string" } } }, "Problem": { "type": "object", "required": [ "title", "status", "code", "requestId" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "description": "Known codes below; clients must tolerate future safe codes within the status class.", "examples": [ "invalid_credentials", "insufficient_scope", "caller_tenant_forbidden", "read_only_api", "invalid_request", "access_denied", "resource_not_found", "rate_limit_exceeded", "report_unavailable", "temporarily_unavailable" ] }, "requestId": { "type": "string" }, "state": { "type": "string", "description": "Optional current report state on download conflict." } } } } }, "x-contract-source": { "path": "source/apps/api/src/Spectra.Infrastructure/ExternalPortal/ExternalPortalContracts.cs", "sha256": "ed32db59879c71ad68dbb668f95ff4e03c3a92d4ef05f73c06df7b7e4c8b8b66" }, "x-compatibility": "Ignore newly added optional fields; do not invent missing/redacted values." }