{ "openapi": "3.1.0", "info": { "title": "Observability API", "version": "1.0.0" }, "servers": [ { "url": "https://api.fenergox.com/tm/observability" } ], "paths": { "/api/v1/transactions/summary": { "get": { "tags": [ "Transactions" ], "summary": "Transaction Ingestion Status By Dates", "description": "Returns the status of transaction requests, categorizing them as successful or failed,\nand grouping the results by date on which the requests were made.", "operationId": "transaction_ingestion_status_by_dates_api_v1_transactions_summary_get", "parameters": [ { "name": "start_date", "in": "query", "required": true, "schema": { "type": "string", "description": "The start date from which the metrics should be generated.", "title": "Start Date" }, "description": "The start date from which the metrics should be generated." }, { "name": "end_date", "in": "query", "required": true, "schema": { "type": "string", "description": "The end date upto which the metrics should be generated.", "title": "End Date" }, "description": "The end date upto which the metrics should be generated." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionIngestionByDate" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/transactions/events": { "get": { "tags": [ "Transactions" ], "summary": "Transaction Ingestion Status By Modifications", "description": "Returns the events for the requested modification external ids.", "operationId": "transaction_ingestion_status_by_modifications_api_v1_transactions_events_get", "parameters": [ { "name": "modification_external_ids", "in": "query", "required": true, "schema": { "type": "string", "description": "The modification_external_ids for which the details should be returned.", "title": "Modification External Ids" }, "description": "The modification_external_ids for which the details should be returned." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionIngestionByModifications" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/transactions/failed-modifications": { "get": { "tags": [ "Transactions" ], "summary": "Failed Modifications Per Date", "description": "Returns the list of failed modifications for the requested date.", "operationId": "failed_modifications_per_date_api_v1_transactions_failed_modifications_get", "parameters": [ { "name": "date", "in": "query", "required": true, "schema": { "type": "string", "description": "The date for which the list of failed modifications should be returned.", "title": "Date" }, "description": "The date for which the list of failed modifications should be returned." } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseFailedModifications" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/batch-transactions/batches": { "get": { "tags": [ "Batch Transactions" ], "summary": "Batch Transactions Batches", "description": "Returns batch transaction information either by batch IDs or by date range.\n\nUse either 'ids' parameter OR both 'start_date' and 'end_date' parameters.", "operationId": "batch_transactions_batches_api_v1_batch_transactions_batches_get", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated batch IDs to retrieve details for.", "title": "Ids" }, "description": "Comma-separated batch IDs to retrieve details for." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The start date from which the metrics should be generated.", "title": "Start Date" }, "description": "The start date from which the metrics should be generated." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The end date up to which the metrics should be generated.", "title": "End Date" }, "description": "The end date up to which the metrics should be generated." } ], "responses": { "200": { "description": "Successful response with batch transaction details", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/BatchDetail" } }, { "type": "array", "items": { "$ref": "#/components/schemas/BatchTransactionsByDateResponse" } } ], "title": "Response Batch Transactions Batches Api V1 Batch Transactions Batches Get" }, "examples": { "by_ids": { "summary": "Batch details retrieved by batch IDs", "value": [ { "batch_id": "batch-123", "status": "completed", "ingest_start": "2023-10-01T10:00:00Z", "ingest_end": "2023-10-01T10:15:00Z", "duration_seconds": 900, "reject_on_invalid": true, "counts": { "total": 1000, "accepted": 950, "invalid": 50 }, "exports": { "s3_location": "s3://bucket/path/to/batch-123" } } ] }, "by_date_range": { "summary": "Batch transactions grouped by date", "value": [ { "date": "2023-10-01", "count": 1, "batches": [ { "batch_id": "batch-123", "status": "completed", "ingest_start": "2023-10-01T10:00:00Z", "ingest_end": "2023-10-01T10:15:00Z", "duration_seconds": 900, "reject_on_invalid": true, "counts": { "total": 1000, "accepted": 950, "invalid": 50 } } ] } ] } } } } }, "400": { "description": "Invalid parameter combination", "content": { "application/json": { "example": { "message": "Invalid parameters. Provide either 'ids' OR both 'start_date' and 'end_date'." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/rules/execution": { "get": { "summary": "Rules Execution Summary", "description": "Returns rule execution information either by rule IDs, execution ID, or by date range.\n\nUse either 'ids' parameter, 'execution_id' parameter, OR both 'start_date' and 'end_date' parameters.", "operationId": "rules_execution_api_v1_rules_execution_get", "parameters": [ { "name": "ids", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comma-separated Rule IDs to retrieve details for.", "title": "Ids" }, "description": "Comma-separated Rule IDs to retrieve details for." }, { "name": "execution_id", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Execution ID to retrieve a summary for.", "title": "Execution Id" }, "description": "Execution ID to retrieve a summary for." }, { "name": "start_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The start date from which the metrics should be generated.", "title": "Start Date" }, "description": "The start date from which the metrics should be generated." }, { "name": "end_date", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The end date up to which the metrics should be generated.", "title": "End Date" }, "description": "The end date up to which the metrics should be generated." } ], "responses": { "200": { "description": "Successful response with rule execution details", "content": { "application/json": { "schema": { "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/RuleExecutionDetail" }, "title": "Rule execution by rule ID(s) filter" }, { "type": "array", "items": { "$ref": "#/components/schemas/RuleExecutionsByDateResponse" }, "title": "Rule execution by dates filter" }, { "$ref": "#/components/schemas/RuleExecutionByExecutionIDSummary", "title": "Rule execution by execution ID filter" } ], "title": "Response Rules Execution Api V1 Rules Execution Get" }, "examples": { "by_ids": { "summary": "Rule execution details retrieved by rule IDs", "value": [ { "rule_id": "rule-123", "status": "completed", "rule_alias": "High Risk Transaction Rule", "rule_description": "This rule checks for high risk transactions.", "total_alerts_received": 25, "unique_alerts_after_deduplication": 20, "rule_effective_date": "2023-10-01", "execution_id": "exec-456" } ] }, "by_date_range": { "summary": "Rule executions grouped by date", "value": [ { "requested_run_date": "2023-10-01", "count": 1, "rules": [ { "rule_id": "rule-123", "status": "completed", "rule_alias": "High Risk Transaction Rule", "rule_description": "This rule checks for high risk transactions.", "total_alerts_received": 25, "unique_alerts_after_deduplication": 20, "rule_effective_date": "2023-10-01", "execution_id": "exec-456" } ] } ] }, "by_execution_id": { "summary": "Completed run \u2013 some rules failed (partially_failed, is_complete: true)", "value": { "execution_id": "exec-456", "requested_run_date": "2026-03-15", "rule_effective_date": "2026-03-15", "overall_status": "partially_failed", "is_complete": true, "total_rules": 12, "completion_percent": 100.0, "progress": { "requested_rules": 0, "started_rules": 0, "succeeded_rules": 10, "failed_rules": 2 }, "alerts": { "total_alerts_received": 245, "unique_alerts_after_deduplication": 198 }, "timing": { "first_event_at": "2026-03-15T00:01:12", "last_event_at": "2026-03-15T00:08:44", "duration_seconds": 452 }, "rules": [ { "rule_id": "rule-001", "status": "succeeded", "rule_alias": "High Risk Transaction Rule", "rule_description": "Flags transactions above risk threshold.", "total_alerts_received": 120, "unique_alerts_after_deduplication": 98 }, { "rule_id": "rule-002", "status": "failed", "rule_alias": "Velocity Check Rule", "total_alerts_received": 0, "unique_alerts_after_deduplication": 0 } ] } }, "by_execution_id_in_progress_with_failures": { "summary": "Running with failures (in_progress_with_failures, is_complete: false)", "value": { "execution_id": "exec-789", "requested_run_date": "2026-03-15", "rule_effective_date": "2026-03-15", "overall_status": "in_progress_with_failures", "is_complete": false, "total_rules": 12, "completion_percent": 50.0, "progress": { "requested_rules": 0, "started_rules": 5, "succeeded_rules": 5, "failed_rules": 2 }, "alerts": { "total_alerts_received": 120, "unique_alerts_after_deduplication": 98 }, "timing": { "first_event_at": "2026-03-15T00:01:12", "last_event_at": "2026-03-15T00:05:00", "duration_seconds": 228 }, "rules": [ { "rule_id": "rule-001", "status": "succeeded", "rule_alias": "High Risk Transaction Rule", "rule_description": "Flags transactions above risk threshold.", "total_alerts_received": 120, "unique_alerts_after_deduplication": 98 }, { "rule_id": "rule-002", "status": "failed", "rule_alias": "Velocity Check Rule", "total_alerts_received": 0, "unique_alerts_after_deduplication": 0 } ] } } } } } }, "400": { "description": "Invalid parameter combination", "content": { "application/json": { "example": { "message": "Invalid parameters. Provide either 'ids', 'execution_id', OR both 'start_date' and 'end_date'." } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/api/v1/data-export/trigger": { "post": { "tags": [ "Data Export" ], "summary": "Request Report", "description": "Request a transaction report for a specific date. Reports are generated asynchronously \u2014 you will receive a job ID straight away and can check its status until the report is ready to download. Each report contains all modification external IDs ingested on the requested date, available as a downloadable JSON file.", "operationId": "request_report_api_v1_data_export_trigger_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTriggerRequest" }, "example": { "report_date": "2026-03-04" } } }, "required": true }, "responses": { "200": { "description": "Report request accepted \u2014 use the returned job_id to check progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTriggerResponse" }, "examples": { "success": { "summary": "Report job created", "value": { "job_id": "7a4a2375-4467-4816-b48f-ccf8a3998c2e" } } } } } }, "400": { "description": "Invalid request \u2014 check that the date is correctly formatted and within the allowed range.", "content": { "application/json": { "examples": { "invalid_format": { "summary": "Date format is incorrect", "value": { "message": "report_date must be in YYYY-MM-DD format" } }, "date_out_of_range": { "summary": "Date is outside the allowed range", "value": { "message": "report_date must not be in the future and must be within the last 30 days" } }, "validation_error": { "summary": "Request could not be validated", "value": { "message": "Validation failed" } } } } } }, "429": { "description": "Too many requests \u2014 you have exceeded the allowed number of report requests. Please wait before trying again.", "content": { "application/json": { "examples": { "hourly_limit": { "summary": "Hourly limit reached", "value": { "message": "Hourly limit exceeded: maximum 1 report request per hour" } }, "daily_limit": { "summary": "Daily limit reached", "value": { "message": "Daily limit exceeded: maximum 10 report requests per day" } }, "unique_reports_limit": { "summary": "Maximum unique reports per day reached", "value": { "message": "Report count guardrail exceeded: maximum 10 unique reports per day" } } } } } }, "500": { "description": "Something went wrong on our end \u2014 the report could not be queued. Please try again later.", "content": { "application/json": { "example": { "message": "Failed to enqueue report generation job" } } } } } } }, "/api/v1/data-export/{job_id}": { "get": { "tags": [ "Data Export" ], "summary": "Get Report Status", "description": "Check the status of a report you have previously requested using the job_id. Once the status shows 'completed', a download link will be included in the response so you can retrieve your JSON report.", "operationId": "get_report_status_endpoint_api_v1_data_export__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "description": "Unique identifier (UUID) returned from the trigger endpoint.", "title": "Job Id" }, "description": "Unique identifier (UUID) returned from the trigger endpoint." } ], "responses": { "200": { "description": "Returns the current status of the report job. Possible statuses: in_progress, completed, failed, or expired. A download link is included once the report is ready.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportStatusResponse" }, "examples": { "in_progress": { "summary": "Export job in progress", "value": { "job_id": "7a4a2375-4467-4816-b48f-ccf8a3998c2e", "status": "in_progress" } }, "completed": { "summary": "Completed with URL", "value": { "job_id": "7a4a2375-4467-4816-b48f-ccf8a3998c2e", "status": "completed", "download_url": "https://dev-prov-clm-dev-observability-reports.s3.eu-central-1.amazonaws.com/reports/dev-prov-clm/7a4a2375-4467-4816-b48f-ccf8a3998c2e/report.json?response-content-disposition=attachment%3B%20filename%3D%22report.json%22&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=900&X-Amz-Signature=...", "expires_at": "2026-03-14T12:40:18.446771+00:00" } }, "failed": { "summary": "Export job failed", "value": { "job_id": "7a4a2375-4467-4816-b48f-ccf8a3998c2e", "status": "failed" } }, "expired": { "summary": "Export job expired", "value": { "job_id": "7a4a2375-4467-4816-b48f-ccf8a3998c2e", "status": "expired", "expires_at": "2026-03-15T12:40:18.446771+00:00" } } } } } }, "400": { "description": "Invalid request \u2014 the URL or job_id appears to be malformed.", "content": { "application/json": { "example": { "message": "Bad Request" } } } }, "404": { "description": "Report job not found \u2014 the provided job_id does not match any existing report request.", "content": { "application/json": { "example": { "message": "Export job not found" } } } }, "500": { "description": "Something went wrong on our end \u2014 we could not retrieve the report status. Please try again later.", "content": { "application/json": { "examples": { "invalid_job": { "summary": "Report job is in an invalid state", "value": { "message": "Report job record is invalid: missing status" } }, "retrieval_error": { "summary": "Could not retrieve the report job", "value": { "message": "Failed to fetch report job from DynamoDB" } } } } } } } } } }, "components": { "schemas": { "BatchCounts": { "properties": { "total": { "anyOf": [ { "type": "integer", "title": "Counts available" }, { "type": "null", "title": "Counts not yet computed" } ], "title": "Total", "description": "Total number of transactions in the batch." }, "accepted": { "anyOf": [ { "type": "integer", "title": "Counts available" }, { "type": "null", "title": "Counts not yet computed" } ], "title": "Accepted", "description": "Number of transactions accepted for ingestion." }, "invalid": { "anyOf": [ { "type": "integer", "title": "Counts available" }, { "type": "null", "title": "Counts not yet computed" } ], "title": "Invalid", "description": "Number of transactions rejected as invalid." } }, "additionalProperties": false, "type": "object", "title": "BatchCounts", "description": "Model for batch counts." }, "BatchDetail": { "properties": { "batch_id": { "type": "string", "title": "Batch Id", "description": "Unique identifier for the batch." }, "status": { "$ref": "#/components/schemas/BatchTransactionIngestionStatus", "description": "Current ingestion status of the batch." }, "ingest_start": { "anyOf": [ { "type": "string", "format": "date-time", "title": "Ingestion started" }, { "type": "null", "title": "Ingestion not yet started" } ], "title": "Ingest Start", "description": "Timestamp when batch ingestion started (UTC, ISO 8601)." }, "ingest_end": { "anyOf": [ { "type": "string", "format": "date-time", "title": "Ingestion completed" }, { "type": "null", "title": "Ingestion not yet completed" } ], "title": "Ingest End", "description": "Timestamp when batch ingestion completed (UTC, ISO 8601)." }, "duration_seconds": { "anyOf": [ { "type": "integer", "title": "Ingestion completed" }, { "type": "null", "title": "Ingestion not yet completed" } ], "title": "Duration Seconds", "description": "Elapsed ingestion time in seconds." }, "counts": { "anyOf": [ { "$ref": "#/components/schemas/BatchCounts", "title": "Counts available" }, { "type": "null", "title": "Counts not yet available" } ], "title": "Counts", "description": "Breakdown of transaction counts by outcome (total, accepted, invalid)." }, "reject_on_invalid": { "anyOf": [ { "type": "boolean", "title": "Configuration known" }, { "type": "null", "title": "Configuration not available" } ], "title": "Reject On Invalid", "description": "Whether the batch was configured to reject all transactions on encountering an invalid one." }, "error_message": { "anyOf": [ { "type": "string", "title": "Batch failed" }, { "type": "null", "title": "No error" } ], "title": "Error Message", "description": "Error message if the batch failed. Null if no error occurred." }, "exports": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object", "title": "Exports generated" }, { "type": "null", "title": "No exports generated" } ], "title": "Exports", "description": "Map of export type to export location (e.g. S3 path). Null if no exports were generated." } }, "additionalProperties": false, "type": "object", "required": [ "batch_id", "status" ], "title": "BatchDetail", "description": "Model for detailed batch information." }, "BatchTransactionIngestionStatus": { "type": "string", "enum": [ "uploaded", "processed", "failed", "validation_failed", "validation_completed", "processed_with_failures", "pending_ingestion", "ingestion_in_progress" ], "title": "BatchTransactionIngestionStatus" }, "BatchTransactionsByDateResponse": { "properties": { "date": { "type": "string", "title": "Date", "description": "Date of the batches in YYYY-MM-DD format." }, "count": { "type": "integer", "title": "Count", "description": "Number of batches on this date." }, "batches": { "items": { "$ref": "#/components/schemas/BatchDetail" }, "type": "array", "title": "Batches", "description": "List of batch details for this date." } }, "additionalProperties": false, "type": "object", "required": [ "date", "count", "batches" ], "title": "BatchTransactionsByDateResponse", "description": "Model for batches grouped by date." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "LinksModifications": { "properties": { "failed_modifications": { "anyOf": [ { "type": "string", "title": "Failed modifications exist" }, { "type": "null", "title": "No failed modifications" } ], "title": "Failed Modifications", "description": "URL to retrieve failed modifications for this date. Null if there are no failures." } }, "additionalProperties": false, "type": "object", "title": "LinksModifications", "description": "Model for links for modifications." }, "ListFailedModifications": { "properties": { "modifications": { "items": { "type": "string" }, "type": "array", "uniqueItems": true, "title": "Modifications", "description": "Set of failed modification external IDs for the requested date." } }, "additionalProperties": false, "type": "object", "required": [ "modifications" ], "title": "ListFailedModifications", "description": "Model for list of failed modifications." }, "ListTransactionModifications": { "properties": { "modifications": { "items": { "$ref": "#/components/schemas/TransactionModification" }, "type": "array", "title": "Modifications", "description": "List of transaction modification event details." } }, "additionalProperties": false, "type": "object", "required": [ "modifications" ], "title": "ListTransactionModifications", "description": "Model for list of transaction modifications." }, "ReportJobStatus": { "type": "string", "enum": [ "in_progress", "completed", "failed", "expired" ], "title": "ReportJobStatus", "description": "Status of a report generation job." }, "ReportStatusResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "The export job identifier." }, "status": { "$ref": "#/components/schemas/ReportJobStatus", "description": "Current status of the job. in_progress: being generated, completed: ready to download, failed: generation failed, expired: file no longer available." }, "download_url": { "anyOf": [ { "type": "string", "title": "Report completed" }, { "type": "null", "title": "Report not yet completed" } ], "title": "Download Url", "description": "Pre-signed download URL. Only present when status is 'completed'. Valid for 15 minutes." }, "expires_at": { "anyOf": [ { "type": "string", "title": "Report completed or expired" }, { "type": "null", "title": "Report not yet completed" } ], "format": "date-time", "title": "Expires At", "description": "ISO 8601 timestamp indicating when the exported file will no longer be available for download." } }, "additionalProperties": false, "type": "object", "required": [ "job_id", "status" ], "title": "ReportStatusResponse", "description": "Model for report status response." }, "ReportTriggerRequest": { "properties": { "report_date": { "type": "string", "format": "date", "title": "Report Date", "description": "The date to export data for, in YYYY-MM-DD format. Must be today or a past date within the allowed lookback window (default: last 30 days)." } }, "additionalProperties": false, "type": "object", "required": [ "report_date" ], "title": "ReportTriggerRequest", "description": "Model for report trigger request." }, "ReportTriggerResponse": { "properties": { "job_id": { "type": "string", "format": "uuid", "title": "Job Id", "description": "Unique identifier (UUID) for the export job. Use this to poll for status." } }, "additionalProperties": false, "type": "object", "required": [ "job_id" ], "title": "ReportTriggerResponse", "description": "Model for report trigger response." }, "ResponseFailedModifications": { "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadata", "description": "Response metadata including total result count." }, "data": { "$ref": "#/components/schemas/ListFailedModifications", "description": "Collection of failed modification external IDs." } }, "additionalProperties": false, "type": "object", "required": [ "metadata", "data" ], "title": "ResponseFailedModifications", "description": "Model for response for failed modifications." }, "ResponseMetadata": { "properties": { "count": { "type": "integer", "title": "Count", "description": "Total number of transaction modification requests." } }, "additionalProperties": false, "type": "object", "required": [ "count" ], "title": "ResponseMetadata", "description": "Model for response metadata." }, "RuleExecutionAlerts": { "properties": { "total_alerts_received": { "anyOf": [ { "type": "integer", "title": "Execution Finished" }, { "type": "null", "title": "Execution In Progress" } ], "title": "Total Alerts Received", "description": "Total number of alerts received across all rules in this execution. Null when the execution is still in progress and no alert data has been indexed yet; 0 when the execution is complete but no alerts were generated." }, "unique_alerts_after_deduplication": { "anyOf": [ { "type": "integer", "title": "Execution Finished" }, { "type": "null", "title": "Execution In Progress" } ], "title": "Unique Alerts After Deduplication", "description": "Number of unique alerts remaining after deduplication. Null when the execution is still in progress and no alert data has been indexed yet; 0 when the execution is complete but no alerts were generated." } }, "additionalProperties": false, "type": "object", "title": "RuleExecutionAlerts", "description": "Aggregated alert counts for an execution.\n\nFields are nullable when the execution is still in progress and no alert data\nhas been indexed yet. They are 0 when the execution is complete but generated\nno alerts (failed or succeeded with no triggers)." }, "RuleExecutionByExecutionIDSummary": { "properties": { "execution_id": { "type": "string", "title": "Execution Id", "description": "Unique identifier for this execution run." }, "requested_run_date": { "type": "string", "title": "Requested Run Date", "description": "The date for which this execution was requested, in YYYY-MM-DD format." }, "rule_effective_date": { "type": "string", "title": "Rule Effective Date", "description": "The effective date of the rules applied in this execution, in YYYY-MM-DD format." }, "overall_status": { "$ref": "#/components/schemas/RuleExecutionOverallStatus", "description": "Aggregate status derived from per-rule outcomes.\n\n**Terminal states** (is_complete=true): succeeded, failed, partially_failed.\n\n**Non-terminal states** (is_complete=false): requested, in_progress, in_progress_with_failures." }, "is_complete": { "type": "boolean", "title": "Is Complete", "description": "True when all rules have reached a terminal state (succeeded or failed)." }, "total_rules": { "type": "integer", "title": "Total Rules", "description": "Total number of rules included in this execution." }, "completion_percent": { "type": "number", "title": "Completion Percent", "description": "Percentage of rules that have completed, calculated as (succeeded_rules + failed_rules) / total_rules * 100." }, "progress": { "$ref": "#/components/schemas/RuleExecutionProgress", "description": "Breakdown of rules by their current status." }, "alerts": { "$ref": "#/components/schemas/RuleExecutionAlerts", "description": "Aggregated alert counts for the entire execution." }, "timing": { "$ref": "#/components/schemas/RuleExecutionTiming", "description": "Timing metrics covering the full span of this execution." }, "rules": { "items": { "$ref": "#/components/schemas/RuleExecutionRuleDetail" }, "type": "array", "title": "Rules", "description": "Per-rule outcome details for all rules in this execution.", "default": [] } }, "additionalProperties": false, "type": "object", "required": [ "execution_id", "requested_run_date", "rule_effective_date", "overall_status", "is_complete", "total_rules", "completion_percent", "progress", "alerts", "timing" ], "title": "RuleExecutionByExecutionIDSummary", "description": "Execution-level summary returned when filtering by execution_id." }, "RuleExecutionDetail": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "Unique identifier for the rule." }, "status": { "$ref": "#/components/schemas/RuleExecutionStatus", "description": "Current execution status of the rule (e.g. requested, started, succeeded, failed)." }, "rule_alias": { "type": "string", "title": "Rule Alias", "description": "Human-readable name or alias for the rule." }, "rule_effective_date": { "type": "string", "title": "Rule Effective Date", "description": "Effective date of the rule applied in this execution, in YYYY-MM-DD format." }, "execution_id": { "type": "string", "title": "Execution Id", "description": "Unique identifier for the execution run this rule belongs to." }, "total_alerts_received": { "anyOf": [ { "type": "integer", "title": "Rule completed" }, { "type": "null", "title": "Rule in progress" } ], "title": "Total Alerts Received", "description": "Total alerts received for this rule. Null when the rule has not yet completed (started or requested); 0 when the rule has completed but generated no alerts." }, "unique_alerts_after_deduplication": { "anyOf": [ { "type": "integer", "title": "Rule completed" }, { "type": "null", "title": "Rule in progress" } ], "title": "Unique Alerts After Deduplication", "description": "Unique alerts remaining after deduplication for this rule. Null when the rule has not yet completed (started or requested); 0 when the rule has completed but generated no alerts." }, "rule_description": { "anyOf": [ { "type": "string", "title": "Description provided" }, { "type": "null", "title": "No description provided" } ], "title": "Rule Description", "description": "Optional free-text description for this rule." } }, "additionalProperties": false, "type": "object", "required": [ "rule_id", "status", "rule_alias", "rule_effective_date", "execution_id" ], "title": "RuleExecutionDetail", "description": "Model for detailed rule execution information." }, "RuleExecutionOverallStatus": { "type": "string", "enum": [ "requested", "in_progress", "in_progress_with_failures", "succeeded", "failed", "partially_failed" ], "title": "RuleExecutionOverallStatus", "description": "Execution-level status derived from the aggregate of per-rule statuses.\n\nTerminal states (is_complete=True):\n SUCCEEDED \u2013 every rule finished successfully.\n FAILED \u2013 every rule that ran finished with a failure.\n PARTIALLY_FAILED \u2013 execution is done, but at least one rule failed\n and at least one succeeded.\n\nNon-terminal states (is_complete=False):\n REQUESTED \u2013 no rule has started yet; all are still queued.\n IN_PROGRESS \u2013 at least one rule is running; no failures so far.\n IN_PROGRESS_WITH_FAILURES \u2013 at least one rule is still running (or\n pending) AND at least one rule has already\n failed mid-flight." }, "RuleExecutionProgress": { "properties": { "requested_rules": { "type": "integer", "title": "Requested Rules", "description": "Number of rules that have been queued but not yet started." }, "started_rules": { "type": "integer", "title": "Started Rules", "description": "Number of rules that have started but not yet reached a terminal state." }, "succeeded_rules": { "type": "integer", "title": "Succeeded Rules", "description": "Number of rules that completed successfully." }, "failed_rules": { "type": "integer", "title": "Failed Rules", "description": "Number of rules that completed with a failure." } }, "additionalProperties": false, "type": "object", "required": [ "requested_rules", "started_rules", "succeeded_rules", "failed_rules" ], "title": "RuleExecutionProgress", "description": "Rule status breakdown for an execution." }, "RuleExecutionRuleDetail": { "properties": { "rule_id": { "type": "string", "title": "Rule Id", "description": "Unique identifier for the rule." }, "status": { "$ref": "#/components/schemas/RuleExecutionStatus", "description": "Current execution status of the rule (e.g. requested, started, succeeded, failed)." }, "rule_alias": { "anyOf": [ { "type": "string", "title": "Alias provided in rule definition" }, { "type": "null", "title": "Alias not provided in rule definition" } ], "title": "Rule Alias", "description": "Human-readable name or alias for the rule, if any." }, "rule_description": { "anyOf": [ { "type": "string", "title": "Description provided in rule definition" }, { "type": "null", "title": "Description not provided in rule definition" } ], "title": "Rule Description", "description": "Optional free-text description of the rule." }, "total_alerts_received": { "anyOf": [ { "type": "integer", "title": "Execution Finished" }, { "type": "null", "title": "Execution In Progress" } ], "title": "Total Alerts Received", "description": "Total alerts received for this rule. Null when the rule has not yet completed (started or requested); 0 when the rule has completed but generated no alerts." }, "unique_alerts_after_deduplication": { "anyOf": [ { "type": "integer", "title": "Execution Finished" }, { "type": "null", "title": "Execution In Progress" } ], "title": "Unique Alerts After Deduplication", "description": "Unique alerts remaining after deduplication for this rule. Null when the rule has not yet completed (started or requested); 0 when the rule has completed but generated no alerts." } }, "additionalProperties": false, "type": "object", "required": [ "rule_id", "status" ], "title": "RuleExecutionRuleDetail", "description": "Per-rule outcome within an execution-level summary.\n\nOmits execution_id and rule_effective_date \u2014 those are at the parent summary level." }, "RuleExecutionStatus": { "type": "string", "enum": [ "requested", "started", "succeeded", "failed" ], "title": "RuleExecutionStatus" }, "RuleExecutionTiming": { "properties": { "first_event_at": { "type": "string", "title": "First Event At", "description": "Timestamp of the first event recorded for this execution (UTC, ISO 8601)." }, "last_event_at": { "type": "string", "title": "Last Event At", "description": "Timestamp of the most recent event recorded for this execution (UTC, ISO 8601)." }, "duration_seconds": { "type": "integer", "title": "Duration Seconds", "description": "Elapsed time in seconds between the first and last recorded events." } }, "additionalProperties": false, "type": "object", "required": [ "first_event_at", "last_event_at", "duration_seconds" ], "title": "RuleExecutionTiming", "description": "Timing metrics for an execution." }, "RuleExecutionsByDateResponse": { "properties": { "requested_run_date": { "type": "string", "title": "Requested Run Date", "description": "Date for which the rules were executed, in YYYY-MM-DD format." }, "count": { "type": "integer", "title": "Count", "description": "Number of rule executions on this date." }, "rules": { "items": { "$ref": "#/components/schemas/RuleExecutionDetail" }, "type": "array", "title": "Rules", "description": "List of rule execution details for this date." } }, "additionalProperties": false, "type": "object", "required": [ "requested_run_date", "count", "rules" ], "title": "RuleExecutionsByDateResponse", "description": "Model for rule executions grouped by run date." }, "TransactionIngestionByDate": { "properties": { "data": { "additionalProperties": { "$ref": "#/components/schemas/TransactionStatusByDate" }, "type": "object", "title": "Data", "description": "Map of date strings (YYYY-MM-DD) to transaction ingestion status counts for that date." } }, "additionalProperties": false, "type": "object", "required": [ "data" ], "title": "TransactionIngestionByDate", "description": "Model for response of transaction status by date." }, "TransactionIngestionByModifications": { "properties": { "metadata": { "$ref": "#/components/schemas/ResponseMetadata", "description": "Response metadata including total results count." }, "data": { "$ref": "#/components/schemas/ListTransactionModifications", "description": "Collection of transaction modification event details." } }, "additionalProperties": false, "type": "object", "required": [ "metadata", "data" ], "title": "TransactionIngestionByModifications", "description": "Model for transaction status by modification." }, "TransactionIngestionStatus": { "type": "string", "enum": [ "succeeded", "failed" ], "title": "TransactionIngestionStatus" }, "TransactionModification": { "properties": { "status": { "$ref": "#/components/schemas/TransactionIngestionStatus", "description": "Ingestion status of the transaction modification." }, "modification_external_id": { "type": "string", "title": "Modification External Id", "description": "External identifier for the modification." }, "transaction_external_id": { "type": "string", "title": "Transaction External Id", "description": "External identifier for the transaction." }, "status_code": { "type": "integer", "title": "Status Code", "description": "HTTP status code returned when the modification was ingested." }, "status_message": { "type": "string", "title": "Status Message", "description": "Human-readable status message returned during ingestion." }, "created_at": { "type": "string", "title": "Created At", "description": "ISO 8601 timestamp indicating when the modification event was recorded." } }, "additionalProperties": false, "type": "object", "required": [ "status", "modification_external_id", "transaction_external_id", "status_code", "status_message", "created_at" ], "title": "TransactionModification", "description": "Model for transaction modification response." }, "TransactionStatusByDate": { "properties": { "succeeded_request_count": { "type": "integer", "title": "Succeeded Request Count", "description": "Number of transaction requests that were successfully ingested on this date." }, "failed_request_count": { "type": "integer", "title": "Failed Request Count", "description": "Number of transaction requests that failed ingestion on this date." }, "links": { "$ref": "#/components/schemas/LinksModifications", "description": "Links to further details for this date (e.g. failed modifications)." } }, "additionalProperties": false, "type": "object", "required": [ "succeeded_request_count", "failed_request_count", "links" ], "title": "TransactionStatusByDate", "description": "Model for transaction status by date." }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "tags": [ { "name": "Transactions", "description": "The Transaction Observability endpoints monitor transactions ingested through the Transactions API. They allow you to monitor ingestion status, view daily success and failure metrics or investigate failed requests using the modification_id. Metrics are calculated per request, not per transaction. Resent or updated transactions are treated as new requests and counted separately. The endpoints support two query modes: Retrieve aggregated metrics grouped by date, Fetch detailed event-level data for specific modification_id values for troubleshooting. Transaction event data is retained based on tenant configuration, typically for 30 days." }, { "name": "Batch Transactions", "description": "The Batch Transactions endpoints provide monitoring for bulk transaction file. They allow you to track the ingestion lifecycle of submitted batch files. You can monitor batch metrics such as total records submitted, records accepted, and marked as failed validation. For failed validation, the response includes pre-signed URLs to download detailed error reports. The endpoints support two query modes: retrieve detailed information for specific batch IDs or fetch aggregated data grouped by upload date. Batch processing data is retained according to tenant configuration, typically for 30 days." }, { "name": "Data Export", "description": "The Data Export feature allows you to generate and download transaction reports for a specific date. Reports contain a list of all modification external IDs that were ingested on the requested date, exported as a downloadable JSON file. The process is asynchronous \u2014 you trigger a report generation, receive a job ID, and then poll for the status until the report is ready for download." } ] }