{ "openapi": "3.1.0", "info": { "title": "Datahub Consumer API", "version": "1.5.0", "description": "Consumer-neutral delivery contract for governed, product-scoped entity snapshots, relationships, documents, entity changes and reproducible organization analytics. A Data Product and its privacy grants determine the fields and sources visible to each Service Account." }, "servers": [ { "url": "/", "description": "Current Datahub origin" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/api/v1/data-products/{dataProduct}/analytics/catalog": { "get": { "operationId": "getAnalyticsCatalog", "summary": "List active Analytics metrics, operations and dimensions", "x-required-ability": "analytics.read", "parameters": [{"$ref": "#/components/parameters/DataProduct"}], "responses": { "200": {"description": "Versioned Analytics catalog"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/api/v1/data-products/{dataProduct}/analytics/analyses": { "post": { "operationId": "createAnalyticsAnalysis", "summary": "Create a reproducible organization analysis", "description": "Precomputed rollup requests can complete synchronously. Complex statistics return 202 and are polled by analysis_uid. Population-dependent and newsworthiness metrics return unsupported_metric.", "x-required-ability": "analytics.read", "parameters": [{"$ref": "#/components/parameters/DataProduct"}], "requestBody": { "required": true, "content": { "application/json": { "schema": {"$ref": "#/components/schemas/AnalyticsQuery"} } } }, "responses": { "200": {"description": "Synchronously completed result", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnalyticsAnalysisEnvelope"}}}}, "202": {"description": "Asynchronous analysis accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnalyticsAnalysisEnvelope"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "422": {"$ref": "#/components/responses/ValidationError"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/api/v1/data-products/{dataProduct}/analytics/analyses/{analysisUid}": { "get": { "operationId": "getAnalyticsAnalysis", "summary": "Get an immutable analysis result snapshot", "x-required-ability": "analytics.read", "parameters": [ {"$ref": "#/components/parameters/DataProduct"}, {"name": "analysisUid", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/Ulid"}} ], "responses": { "200": {"description": "Current state and immutable completed snapshot", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AnalyticsAnalysisEnvelope"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/api/v1/data-products/{dataProduct}/analytics/analyses/{analysisUid}/entities": { "get": { "operationId": "getAnalyticsAnalysisEntities", "summary": "List organizations underlying an analysis", "description": "Returns paginated external organization UIDs only. Persons and person-related matching evidence are never returned.", "x-required-ability": "analytics.entities.read", "parameters": [ {"$ref": "#/components/parameters/DataProduct"}, {"name": "analysisUid", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/Ulid"}}, {"$ref": "#/components/parameters/PerPage"} ], "responses": { "200": {"description": "Organization-only drill-down"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/api/v1/data-products/{dataProduct}/analytics/anomalies": { "get": { "operationId": "listAnalyticsAnomalies", "summary": "List statistically supported anomaly candidates", "x-required-ability": "analytics.read", "parameters": [{"$ref": "#/components/parameters/DataProduct"}, {"$ref": "#/components/parameters/PerPage"}], "responses": { "200": {"description": "Paginated anomaly candidates with structured statistical reasons"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/api/v1/data-products/{dataProduct}/analytics/anomalies/{anomalyUid}": { "get": { "operationId": "getAnalyticsAnomaly", "summary": "Get an anomaly candidate and its statistical explanation", "x-required-ability": "analytics.read", "parameters": [ {"$ref": "#/components/parameters/DataProduct"}, {"name": "anomalyUid", "in": "path", "required": true, "schema": {"$ref": "#/components/schemas/Ulid"}} ], "responses": { "200": {"description": "Anomaly candidate"}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "403": {"$ref": "#/components/responses/Forbidden"}, "404": {"$ref": "#/components/responses/NotFound"}, "429": {"$ref": "#/components/responses/RateLimited"} } } }, "/api/v1/data-products/{dataProduct}/entities": { "get": { "operationId": "findDataProductEntities", "summary": "Find entities by namespaced identifier", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "name": "namespace", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 100 } }, { "name": "identifier", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 255 } }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Product-scoped entity snapshots", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySnapshotCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}": { "get": { "operationId": "getDataProductEntity", "summary": "Get the current product-scoped entity snapshot", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" } ], "responses": { "200": { "description": "Current entity snapshot", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/EntitySnapshot" } }, "additionalProperties": false } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/materializations": { "post": { "operationId": "requestDataProductEntityMaterialization", "summary": "Prioritize materialization of an incomplete organization", "description": "Queues a governed, idempotent HVD refresh. The enriched target also runs GISA and matching; documents additionally retrieves and processes structured HVD documents. GET requests never trigger materialization.", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMaterializationInput" } } } }, "responses": { "200": { "description": "The materialization is already terminal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMaterializationResponse" } } } }, "202": { "description": "The materialization was queued or is still running", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Retry-After": { "schema": { "type": "integer", "const": 30 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMaterializationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/materializations/{materializationRequest}": { "get": { "operationId": "getDataProductEntityMaterialization", "summary": "Get prioritized entity materialization status", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" }, { "$ref": "#/components/parameters/MaterializationRequest" } ], "responses": { "200": { "description": "Current or terminal materialization status", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMaterializationResponse" } } } }, "202": { "description": "The materialization is still queued or running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMaterializationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/relationships": { "get": { "operationId": "listDataProductEntityRelationships", "summary": "List product-scoped relationships for an entity", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Relationships visible through the Data Product", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Relationship" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/documents": { "get": { "operationId": "listDataProductEntityDocuments", "summary": "List product-scoped document metadata for an entity", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Documents visible through the Data Product", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/documents/{documentUid}/content": { "get": { "operationId": "downloadDataProductDocumentContent", "summary": "Download the immutable original document", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" }, { "$ref": "#/components/parameters/DocumentUid" } ], "responses": { "200": { "description": "Original content delivered as an attachment", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" }, "Content-Disposition": { "description": "Attachment filename", "schema": { "type": "string" } }, "X-Content-Type-Options": { "description": "Always nosniff", "schema": { "type": "string", "const": "nosniff" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentEncoding": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/documents/{documentUid}/content-requests": { "post": { "operationId": "requestDataProductDocumentContent", "summary": "Request materialization of a remotely available document", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" }, { "$ref": "#/components/parameters/DocumentUid" } ], "responses": { "200": { "description": "Content was already available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentRequestResponse" } } } }, "202": { "description": "Retrieval is queued or running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentRequestResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/data-products/{dataProduct}/entities/{entityUid}/documents/{documentUid}/content-requests/{contentRequest}": { "get": { "operationId": "getDataProductDocumentContentRequest", "summary": "Read document materialization status", "parameters": [ { "$ref": "#/components/parameters/DataProduct" }, { "$ref": "#/components/parameters/EntityUid" }, { "$ref": "#/components/parameters/DocumentUid" }, { "$ref": "#/components/parameters/ContentRequestUid" } ], "responses": { "200": { "description": "Current terminal or non-terminal request status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentRequestResponse" } } } }, "202": { "description": "Retrieval is still queued or running", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentContentRequestResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/entity-subscriptions": { "get": { "operationId": "listEntitySubscriptions", "summary": "List the Consumer watchlist for a Data Product", "parameters": [ { "$ref": "#/components/parameters/DataProductQuery" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "disabled" ], "default": "active" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "Consumer-owned Entity subscriptions", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySubscriptionCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/entity-subscriptions/{entity}": { "put": { "operationId": "upsertEntitySubscription", "summary": "Idempotently activate or replace an Entity subscription", "parameters": [ { "$ref": "#/components/parameters/SubscriptionEntity" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySubscriptionInput" } } } }, "responses": { "200": { "description": "Current idempotent subscription state", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "operationId": "disableEntitySubscription", "summary": "Idempotently disable an Entity subscription", "parameters": [ { "$ref": "#/components/parameters/SubscriptionEntity" }, { "$ref": "#/components/parameters/DataProductQuery" } ], "responses": { "200": { "description": "Disabled subscription state", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntitySubscriptionResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/entity-subscriptions/changes": { "get": { "operationId": "listSubscribedEntityChanges", "summary": "Read changes only for the Consumer watchlist", "description": "The next cursor is the last scanned global change. It can advance past changes excluded by subscription event or field filters.", "parameters": [ { "$ref": "#/components/parameters/DataProductQuery" }, { "$ref": "#/components/parameters/ChangeCursor" }, { "$ref": "#/components/parameters/ChangeLimit" } ], "responses": { "200": { "description": "Strictly ascending page of watched Entity changes", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityChangeCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/api/v1/changes/entities": { "get": { "operationId": "listEntityChanges", "summary": "Read an ordered Entity Delta Feed", "parameters": [ { "$ref": "#/components/parameters/DataProductQuery" }, { "$ref": "#/components/parameters/ChangeCursor" }, { "$ref": "#/components/parameters/ChangeLimit" } ], "responses": { "200": { "description": "Strictly ascending page of product-routed entity changes", "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityChangeCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthenticated" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "entityChange": { "post": { "operationId": "receiveEntityChangeWebhook", "summary": "Receive an at-least-once hint for a watched Entity change", "description": "Consumers acknowledge with any 2xx response and reconcile authoritative order through the subscribed cursor feed. No canonical field values are sent.", "security": [], "parameters": [ { "name": "X-Backbone-Delivery", "in": "header", "required": true, "schema": { "$ref": "#/components/schemas/Ulid" } }, { "name": "X-Backbone-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[0-9]+$" } }, { "name": "X-Backbone-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-f0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityChangeWebhook" } } } }, "responses": { "200": { "description": "The Consumer accepted the hint" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "edb_" } }, "headers": { "RequestId": { "description": "Caller-supplied UUID or server-generated correlation UUID", "schema": { "type": "string", "format": "uuid" } } }, "parameters": { "DataProduct": { "name": "dataProduct", "in": "path", "required": true, "description": "External immutable Data Product UID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "DataProductQuery": { "name": "data_product", "in": "query", "required": true, "description": "External immutable Data Product UID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "SubscriptionEntity": { "name": "entity", "in": "path", "required": true, "description": "External Entity ULID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "ChangeCursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9]+$", "default": "0" } }, "ChangeLimit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, "EntityUid": { "name": "entityUid", "in": "path", "required": true, "description": "External Entity ULID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "DocumentUid": { "name": "documentUid", "in": "path", "required": true, "description": "External Document ULID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "ContentRequestUid": { "name": "contentRequest", "in": "path", "required": true, "description": "External document content request ULID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "MaterializationRequest": { "name": "materializationRequest", "in": "path", "required": true, "description": "External entity materialization request ULID", "schema": { "$ref": "#/components/schemas/Ulid" } }, "Page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } }, "responses": { "Unauthenticated": { "description": "Missing, invalid, expired or revoked Service Account token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "The Consumer, grant, Data Product or token ability does not authorize this operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource does not exist within the product scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Request validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "RateLimited": { "description": "Consumer rate limit reached", "headers": { "Retry-After": { "description": "Seconds until another request should be attempted", "schema": { "type": "integer", "minimum": 0 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "AnalyticsQuery": { "type": "object", "required": ["metric", "operation", "time_grain", "from", "to"], "properties": { "metric": {"type": "string", "maxLength": 120}, "operation": { "type": "string", "enum": ["count", "sum", "avg", "median", "rate", "change", "mom_change", "yoy_change", "rolling_7_days", "rolling_30_days", "rolling_90_days", "rank", "percentile", "record", "trend", "acceleration", "anomaly", "correlation", "cohort", "survival"] }, "time_grain": {"type": "string", "enum": ["day", "iso_week", "month", "quarter", "year"]}, "from": {"type": "string", "format": "date"}, "to": {"type": "string", "format": "date"}, "as_of": {"type": ["string", "null"], "format": "date"}, "comparison_mode": {"type": ["string", "null"], "enum": ["none", "previous_period", "previous_year", null]}, "comparison_metric": {"type": ["string", "null"]}, "dimensions": {"type": "array", "maxItems": 2, "uniqueItems": true, "items": {"type": "string"}}, "filters": {"type": "object", "additionalProperties": true}, "sort": {"type": ["string", "null"], "enum": ["value_asc", "value_desc", "time_asc", "time_desc", null]}, "limit": {"type": ["integer", "null"], "minimum": 1, "maximum": 1000}, "minimum_sample_size": {"type": ["integer", "null"], "minimum": 1}, "statistic": {"type": ["object", "null"], "additionalProperties": true} }, "additionalProperties": false }, "AnalyticsAnalysis": { "type": "object", "required": ["analysis_uid", "status", "method_version", "query_fingerprint", "query", "source_watermarks"], "properties": { "analysis_uid": {"$ref": "#/components/schemas/Ulid"}, "status": {"type": "string", "enum": ["pending", "running", "completed", "insufficient_data", "unsupported_metric", "failed"]}, "metric_version": {"type": ["string", "null"]}, "method_version": {"type": "string"}, "data_universe": {"type": ["string", "null"]}, "data_as_of": {"type": ["string", "null"], "format": "date"}, "query_fingerprint": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "query": {"$ref": "#/components/schemas/AnalyticsQuery"}, "result": {"type": ["object", "null"], "additionalProperties": true}, "coverage": {"type": ["object", "null"], "additionalProperties": true}, "exclusions": {"type": ["object", "null"], "additionalProperties": true}, "source_watermarks": {"type": "object", "additionalProperties": true}, "error": {"type": ["object", "null"], "additionalProperties": true}, "requested_at": {"type": ["string", "null"], "format": "date-time"}, "finished_at": {"type": ["string", "null"], "format": "date-time"} }, "additionalProperties": false }, "AnalyticsAnalysisEnvelope": { "type": "object", "required": ["data"], "properties": {"data": {"$ref": "#/components/schemas/AnalyticsAnalysis"}}, "additionalProperties": false }, "Ulid": { "type": "string", "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "ValidationError": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "required": [ "errors" ], "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } ] }, "EntitySnapshot": { "type": "object", "required": [ "entity_uid", "entity_version_uid", "jurisdiction", "data_product_uid", "schema_version", "data" ], "properties": { "entity_uid": { "$ref": "#/components/schemas/Ulid" }, "entity_version_uid": { "$ref": "#/components/schemas/Ulid" }, "jurisdiction": { "type": [ "string", "null" ] }, "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "schema_version": { "type": "string" }, "data": { "type": "object", "description": "Canonical fields selected by the immutable Data Product contract", "additionalProperties": true } }, "additionalProperties": false }, "EntitySnapshotCollection": { "allOf": [ { "$ref": "#/components/schemas/PaginatedResponse" }, { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySnapshot" } } } } ] }, "Relationship": { "type": "object", "required": [ "relationship_uid", "from_entity_uid", "to_entity_uid", "type", "strength", "status", "privacy_classification", "source" ], "properties": { "relationship_uid": { "$ref": "#/components/schemas/Ulid" }, "from_entity_uid": { "$ref": "#/components/schemas/Ulid" }, "to_entity_uid": { "$ref": "#/components/schemas/Ulid" }, "type": { "type": "string" }, "strength": { "type": "string" }, "role_code": { "type": [ "string", "null" ] }, "role_label": { "type": [ "string", "null" ] }, "valid_from": { "type": [ "string", "null" ], "format": "date" }, "valid_to": { "type": [ "string", "null" ], "format": "date" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string" }, "privacy_classification": { "type": "string" }, "source": { "$ref": "#/components/schemas/SourceReference" } }, "additionalProperties": false }, "SourceReference": { "type": "object", "required": [ "source_uid", "source_record_uid" ], "properties": { "source_uid": { "$ref": "#/components/schemas/Ulid" }, "source_record_uid": { "$ref": "#/components/schemas/Ulid" }, "attribution": { "type": [ "string", "null" ] } } }, "Document": { "type": "object", "required": [ "document_uid", "document_type", "source", "content", "original", "financials", "content_url", "content_request_url" ], "properties": { "document_uid": { "$ref": "#/components/schemas/Ulid" }, "document_type": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "document_date": { "type": [ "string", "null" ], "format": "date" }, "as_of_date": { "type": [ "string", "null" ], "format": "date" }, "source": { "$ref": "#/components/schemas/SourceReference" }, "content": { "$ref": "#/components/schemas/DocumentContent" }, "original": { "oneOf": [ { "$ref": "#/components/schemas/DocumentOriginal" }, { "type": "null" } ] }, "financials": { "type": "array", "items": { "$ref": "#/components/schemas/FinancialFact" } }, "content_url": { "type": [ "string", "null" ], "format": "uri" }, "content_request_url": { "type": [ "string", "null" ], "format": "uri" } }, "additionalProperties": false }, "DocumentContent": { "type": "object", "required": [ "status", "reason", "expected_mime_type", "expected_content_length", "basis_document_uid" ], "properties": { "status": { "type": "string", "enum": [ "remote_available", "queued", "retrieving", "available", "failed", "unavailable" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "eager_policy", "metadata_only_policy", "structured_only_policy", "structured_alternative_available", "xml_fallback", "consumer_requested", "operator_requested", null ] }, "expected_mime_type": { "type": [ "string", "null" ] }, "expected_content_length": { "type": [ "integer", "null" ], "minimum": 0 }, "basis_document_uid": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] } }, "additionalProperties": false }, "EntityMaterializationInput": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "core", "enriched", "documents" ], "default": "enriched" } }, "additionalProperties": false }, "EntityMaterializationResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "request_uid", "entity_uid", "target", "current_level", "status", "stages", "error_code", "requested_at", "started_at", "finished_at", "status_url", "entity_url" ], "properties": { "request_uid": { "$ref": "#/components/schemas/Ulid" }, "entity_uid": { "$ref": "#/components/schemas/Ulid" }, "target": { "type": "string", "enum": [ "core", "enriched", "documents" ] }, "current_level": { "type": "string", "enum": [ "known", "core", "enriched", "documents" ] }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "completed_with_warnings", "failed" ] }, "stages": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "pending", "queued", "running", "completed", "completed_with_warnings", "failed" ] } }, "error_code": { "type": [ "string", "null" ] }, "requested_at": { "type": "string", "format": "date-time" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "status_url": { "type": "string", "format": "uri" }, "entity_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "additionalProperties": false }, "DocumentContentRequestResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "request_uid", "status", "content_status", "error_code", "status_url", "content_url" ], "properties": { "request_uid": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "enum": [ "queued", "retrieving", "available", "failed", "unavailable" ] }, "content_status": { "type": "string", "enum": [ "remote_available", "queued", "retrieving", "available", "failed", "unavailable" ] }, "error_code": { "type": [ "string", "null" ] }, "status_url": { "type": "string", "format": "uri" }, "content_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } }, "additionalProperties": false }, "DocumentOriginal": { "type": "object", "required": [ "original_uid", "sha256", "mime_type", "content_length", "processing_status", "processing_reason", "processing_basis_original_uid", "derivatives" ], "properties": { "original_uid": { "$ref": "#/components/schemas/Ulid" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "mime_type": { "type": "string" }, "content_length": { "type": "integer", "minimum": 0 }, "processing_status": { "type": "string", "enum": [ "pending", "processing", "completed", "not_required", "failed" ] }, "processing_reason": { "type": [ "string", "null" ], "enum": [ "structured_alternative_available", null ] }, "processing_basis_original_uid": { "oneOf": [ { "$ref": "#/components/schemas/Ulid" }, { "type": "null" } ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "derivatives": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentDerivative" } } }, "additionalProperties": false }, "DocumentDerivative": { "type": "object", "required": [ "derivative_uid", "type", "sha256", "mime_type", "status" ], "properties": { "derivative_uid": { "$ref": "#/components/schemas/Ulid" }, "type": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "mime_type": { "type": "string" }, "tool": { "type": [ "string", "null" ] }, "tool_version": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "additionalProperties": false }, "FinancialFact": { "type": "object", "required": [ "financial_uid", "concept_name" ], "properties": { "financial_uid": { "$ref": "#/components/schemas/Ulid" }, "concept_namespace": { "type": [ "string", "null" ] }, "concept_name": { "type": "string" }, "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "period_instant": { "type": [ "string", "null" ], "format": "date" }, "unit": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "value": {}, "source_path": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "PaginationLinks": { "type": "object", "required": [ "first", "last", "prev", "next" ], "properties": { "first": { "type": "string", "format": "uri" }, "last": { "type": "string", "format": "uri" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" } }, "additionalProperties": false }, "PaginationMeta": { "type": "object", "required": [ "data_product_uid", "schema_version", "current_page", "last_page", "per_page", "total" ], "properties": { "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "schema_version": { "type": "string" }, "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ] }, "last_page": { "type": "integer", "minimum": 1 }, "per_page": { "type": "integer", "minimum": 1 }, "to": { "type": [ "integer", "null" ] }, "total": { "type": "integer", "minimum": 0 } } }, "PaginatedResponse": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": {} }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } }, "EntityChange": { "type": "object", "required": [ "cursor", "change_uid", "change_type", "entity_uid", "entity_version_uid", "changed_fields", "occurred_at" ], "properties": { "cursor": { "type": "string", "pattern": "^[0-9]+$" }, "change_uid": { "$ref": "#/components/schemas/Ulid" }, "change_type": { "type": "string" }, "entity_uid": { "$ref": "#/components/schemas/Ulid" }, "entity_version_uid": { "$ref": "#/components/schemas/Ulid" }, "changed_fields": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "occurred_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "EntitySubscriptionInput": { "type": "object", "required": [ "data_product" ], "properties": { "data_product": { "$ref": "#/components/schemas/Ulid" }, "event_types": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "default": [ "*" ], "items": { "type": "string", "enum": [ "*", "entity.created", "entity.updated" ] } }, "field_patterns": { "type": "array", "maxItems": 50, "uniqueItems": true, "default": [], "items": { "type": "string", "maxLength": 255, "pattern": "^[A-Za-z0-9_.*-]+$" } } }, "additionalProperties": false }, "EntitySubscription": { "type": "object", "required": [ "subscription_uid", "data_product_uid", "entity_uid", "event_types", "field_patterns", "starts_after_cursor", "status", "created_at", "updated_at", "disabled_at" ], "properties": { "subscription_uid": { "$ref": "#/components/schemas/Ulid" }, "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "entity_uid": { "$ref": "#/components/schemas/Ulid" }, "event_types": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "field_patterns": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "starts_after_cursor": { "type": "string", "pattern": "^[0-9]+$" }, "status": { "type": "string", "enum": [ "active", "disabled" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "disabled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "additionalProperties": false }, "EntitySubscriptionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "oneOf": [ { "$ref": "#/components/schemas/EntitySubscription" }, { "$ref": "#/components/schemas/DisabledEntitySubscriptionState" } ] } }, "additionalProperties": false }, "DisabledEntitySubscriptionState": { "type": "object", "required": [ "subscription_uid", "data_product_uid", "entity_uid", "status" ], "properties": { "subscription_uid": { "type": [ "string", "null" ], "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$" }, "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "entity_uid": { "$ref": "#/components/schemas/Ulid" }, "status": { "type": "string", "const": "disabled" } }, "additionalProperties": false }, "EntitySubscriptionCollection": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntitySubscription" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "type": "object", "required": [ "data_product_uid", "current_page", "last_page", "per_page", "total" ], "properties": { "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" } }, "additionalProperties": false } }, "additionalProperties": false }, "EntityChangeWebhook": { "type": "object", "required": [ "event_uid", "event_type", "request_id", "occurred_at", "data_product", "subscription_uid", "entity" ], "properties": { "event_uid": { "$ref": "#/components/schemas/Ulid" }, "event_type": { "type": "string", "enum": [ "entity.created", "entity.updated" ] }, "request_id": { "type": "string", "format": "uuid" }, "occurred_at": { "type": "string", "format": "date-time" }, "data_product": { "type": "object", "required": [ "data_product_uid", "schema_version" ], "properties": { "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "schema_version": { "type": "string" } }, "additionalProperties": false }, "subscription_uid": { "$ref": "#/components/schemas/Ulid" }, "entity": { "type": "object", "required": [ "entity_uid", "entity_version_uid", "change_uid", "cursor", "changed_fields" ], "properties": { "entity_uid": { "$ref": "#/components/schemas/Ulid" }, "entity_version_uid": { "$ref": "#/components/schemas/Ulid" }, "change_uid": { "$ref": "#/components/schemas/Ulid" }, "cursor": { "type": "string", "pattern": "^[0-9]+$" }, "changed_fields": { "type": "array", "items": { "type": "string" }, "uniqueItems": true } }, "additionalProperties": false } }, "additionalProperties": false }, "EntityChangeCollection": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EntityChange" } }, "meta": { "type": "object", "required": [ "data_product_uid", "data_product_key", "schema_version", "next_cursor", "has_more" ], "properties": { "data_product_uid": { "$ref": "#/components/schemas/Ulid" }, "data_product_key": { "type": "string" }, "schema_version": { "type": "string" }, "next_cursor": { "type": "string", "pattern": "^[0-9]+$" }, "has_more": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }