--- updatedAt: 2026-08-31T03:40:46.000Z agentTools: projectIndex: https://readme.cipherowl.ai/llms.txt --- # List a Case's Screening history Returns one page of the Case's append-only Screening history, newest first, with the total entry count: each Trigger with its provenance, its evidence acquisition lifecycle, and its artifact bindings. Entries are never removed or rewritten, but lifecycle fields settle after an entry first appears — re-read an entry rather than caching it as final. Large captured content is excluded. # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "API ENDPOINTS", "description": "CipherOwl blockchain compliance and risk assessment APIs.", "version": "1.0" }, "servers": [ { "url": "https://svc.cipherowl.ai" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Case Management", "description": "Read the organization's compliance cases. Search and page the case queue, read one case with the screening route currently in force for its address, its append-only screening history, and its audit trail. Read-only: cases are opened by screening (or by hand in the CipherOwl console), worked and closed there, and no write route is published here. A Case identifies its address by `network`; Cases opened today store the chain there (e.g. `evm`)." } ], "paths": { "/api/case-management/v1/cases/{caseId}/screenings": { "get": { "summary": "List a Case's Screening history", "description": "Returns one page of the Case's append-only Screening history, newest first, with the total entry count: each Trigger with its provenance, its evidence acquisition lifecycle, and its artifact bindings. Entries are never removed or rewritten, but lifecycle fields settle after an entry first appears — re-read an entry rather than caching it as final. Large captured content is excluded.", "operationId": "CaseManagementService_ListCaseScreenings", "responses": { "200": { "description": "A successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/case_managementv1ListCaseScreeningsResponse" } } } } }, "parameters": [ { "name": "caseId", "description": "Identifier of the Case (Case.id).", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "pageSize", "description": "Entries per page, 1 to 100. Omitted or 0 means 50.", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "page", "description": "Page to return, starting at 1; omitted or 0 returns page 1. Pages beyond\n10000 are rejected.", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } } ], "tags": [ "Case Management" ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth 2.0 access token obtained from /oauth/token using client credentials." } }, "schemas": { "case_managementv1CaseScreening": { "type": "object", "properties": { "trigger": { "allOf": [ { "$ref": "#/components/schemas/v1TriggerProvenance" } ], "description": "The event this entry records, with its immutable provenance." }, "ingestOrigin": { "allOf": [ { "$ref": "#/components/schemas/v1ScreeningIngestOrigin" } ], "description": "How the Screening entered the Case; see ScreeningIngestOrigin." }, "addedBy": { "type": "string", "description": "Subject id of the user who added this Screening by hand; absent for\nautomatic intake." }, "evidenceSetId": { "type": "string", "description": "Identifier of the evidence set gathered for this Screening." }, "acquisition": { "allOf": [ { "$ref": "#/components/schemas/v1ScreeningAcquisition" } ], "description": "Progress of fetching the Risk Reason Detail for this Screening; absent\nwhen none is fetched for it." }, "riskReasonDetail": { "allOf": [ { "$ref": "#/components/schemas/v1ScreeningEvidenceItem" } ], "description": "The Risk Reason Detail captured for this Screening; absent when none is\nfetched for it." }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/v1ScreeningArtifact" }, "description": "Artifacts derived from this Screening's evidence." } }, "description": "CaseScreening is one entry in the Case's append-only Screening history: the\nevent that added it (the Trigger), how it entered the Case, and the evidence\ngathered for it — the Risk Reason Detail fetch, the captured evidence item,\nand the artifacts derived from it. An entry is never removed or rewritten,\nbut its acquisition, riskReasonDetail and artifacts are read live and\nsettle after the entry first appears (the evidence item moves from PENDING\nto READY and gains observedAt and contentId), so re-read an entry rather\nthan caching it as final. The captured evidence content itself is not\nincluded. For a Case opened by hand, the creation entry is listed too —\ntell it apart by trigger.triggerType / ingestOrigin." }, "case_managementv1ListCaseScreeningsResponse": { "type": "object", "properties": { "screenings": { "type": "array", "items": { "$ref": "#/components/schemas/case_managementv1CaseScreening" }, "description": "One page of the Case's Screening history." }, "totalCount": { "type": "string", "format": "int64", "description": "Total Screening history entries for the Case across all pages." }, "page": { "type": "integer", "format": "int32", "description": "Echo of the served 1-based page number." }, "pageSize": { "type": "integer", "format": "int32", "description": "Echo of the served page size." } }, "description": "ListCaseScreeningsResponse is one page of a Case's Screening history,\nnewest first, plus the total entry count." }, "v1ScreeningAcquisition": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique Acquisition identifier." }, "status": { "type": "string", "description": "Progress: PENDING (queued, or waiting to retry), IN_PROGRESS (fetching) or\nREADY (the evidence is captured)." }, "attempts": { "type": "integer", "format": "int32", "description": "Number of times a worker has claimed the fetch so far; a claim counts\neven when the worker did not reach the evidence service." }, "requestStartedAt": { "type": "string", "format": "date-time", "description": "When the fetch that captured the evidence started; absent until the\nAcquisition is READY (failed attempts do not record it)." }, "responseReceivedAt": { "type": "string", "format": "date-time", "description": "When the evidence response arrived; absent until the Acquisition is READY." }, "upstreamVersion": { "type": "string", "description": "Version the evidence service reported for its response, when it did." }, "validator": { "type": "string", "description": "Response validator (for example an ETag) the evidence service provided,\nwhen it did." }, "notModified": { "type": "boolean", "description": "True when a re-fetch confirmed the previously captured evidence unchanged." }, "lastFailureClass": { "type": "string", "description": "Category of the latest failed attempt, from a fixed vocabulary; cleared\nwhen the next attempt starts." } }, "description": "ScreeningAcquisition is the progress of fetching the Risk Reason Detail\n(the evidence behind a screening hit) for one Screening. Status is PENDING,\nIN_PROGRESS or READY. A failed attempt is not final: it returns the\nAcquisition to PENDING for a later retry, raises attempts, and names the\ncause on lastFailureClass, which the next attempt clears." }, "v1ScreeningArtifact": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this artifact binding." }, "kind": { "type": "string", "description": "Which artifact: GRAPH (fund-flow graph), NARRATIVE (written narrative of\nthe evidence) or SAR_DRAFT (draft suspicious activity report)." }, "status": { "type": "string", "description": "Progress of producing the artifact: WAITING_FOR_INPUT (the evidence it is\nbuilt from is not captured yet), PENDING or IN_PROGRESS (an output is\nselected and being produced — the output's state when it was selected,\nkept until the output is READY, so a retried failure does not change it)\nor READY. There is no failed state: treat anything but READY as not\nready yet." }, "resolution": { "type": "string", "description": "How the selected output is obtained: FETCHED (retrieved from the\nproducing service), GENERATED (produced for this Screening) or REUSED (an\nexisting output built from identical inputs). Set as soon as an output is\nselected, so it is normally present while status is still PENDING; absent\nonly while WAITING_FOR_INPUT." }, "artifactOutputId": { "type": "string", "description": "Identifier of the selected artifact output; absent while\nWAITING_FOR_INPUT. An output never changes once written, and a REUSED\noutput is shared with the Screening that first produced it." }, "resolvedAt": { "type": "string", "format": "date-time", "description": "When the artifact became READY; absent before then." } }, "description": "ScreeningArtifact is one derived artifact of a Screening's evidence — the\nfund-flow graph, the narrative, or the SAR draft — and how it was produced.\nOnly READY is final; every other status means the artifact is not ready." }, "v1ScreeningEvidenceItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of this evidence item." }, "status": { "type": "string", "description": "PENDING until the evidence is captured, READY from then on." }, "observedAt": { "type": "string", "format": "date-time", "description": "When the evidence was captured; absent while PENDING." }, "contentId": { "type": "string", "description": "Reference to the captured evidence content, which never changes once\nwritten. Two Screenings in one organization that received identical\nevidence may share the same contentId while keeping their own item ids." } }, "description": "ScreeningEvidenceItem identifies the Risk Reason Detail captured for one\nScreening. Status is PENDING until the evidence is captured and READY from\nthen on; a failed fetch attempt leaves the Item PENDING and is reported on\nthe Acquisition instead." }, "v1ScreeningIngestOrigin": { "type": "string", "enum": [ "SCREENING_INGEST_ORIGIN_UNSPECIFIED", "SCREENING_INGEST_ORIGIN_AUTOMATIC", "SCREENING_INGEST_ORIGIN_USER_ADDED", "SCREENING_INGEST_ORIGIN_MANUAL" ], "default": "SCREENING_INGEST_ORIGIN_UNSPECIFIED", "description": "ScreeningIngestOrigin is how a Screening entered the Case, so that a result\na user recorded by hand is never mistaken for an automatic screening hit.\n\n - SCREENING_INGEST_ORIGIN_AUTOMATIC: A screening hit delivered automatically by the screening pipeline.\n - SCREENING_INGEST_ORIGIN_USER_ADDED: A screening result a user added to the Case by hand in the console.\n - SCREENING_INGEST_ORIGIN_MANUAL: The creation entry of a Case that was opened by hand rather than by a\nscreening hit." }, "v1TriggerProvenance": { "type": "object", "properties": { "triggerId": { "type": "string", "description": "Unique identifier of this Trigger." }, "triggerType": { "type": "string", "description": "\"SCREENING\" for a screening result (automatic or user-added), \"MANUAL\"\nfor the creation entry of a Case opened by hand." }, "sourceEventId": { "type": "string", "description": "Identifier of the source screening event, as its producer assigned it.\nAbsent for a user-added result and for the creation entry of a Case\nopened by hand — neither has a source event." }, "source": { "type": "string", "description": "Where the source event came from: \"SCREENING\" for a screening-service\nhit, \"MONITORING\" for a continuous-monitoring hit, the source a user gave\nwhen recording a result by hand, or \"MANUAL_CASE_CREATION\" for the\ncreation entry of a Case opened by hand." }, "sourcePoolId": { "type": "string", "description": "Address pool the source event named — the continuous-monitoring pool the\nhit came from; absent when the event named none." }, "schemaVersion": { "type": "integer", "format": "int32", "description": "Schema revision of the source screening event. Absent for a user-added\nresult; the creation entry of a Case opened by hand records 1." }, "screeningVersion": { "type": "string", "description": "Which screening decision source produced a screening-service hit: a\nrisk-data (bloom filter) version, \"override\" for a private-data override,\nor \"firewall://\" for a firewall rule. Absent when the source reported\nnone — continuous-monitoring hits and older screening events." }, "riskConfig": { "type": "string", "description": "Risk configuration the screening was evaluated under." }, "network": { "type": "string", "description": "Network or chain named by the source event: a screening hit names the\nnetwork it screened (e.g. \"ethereum_mainnet\"), a continuous-monitoring\nhit names the chain (e.g. \"evm\"), a user-added result carries the Case's\nown network value, and a Case opened by hand carries the value named when\nit was opened. chain_class always holds the chain." }, "address": { "type": "string", "description": "Address the Trigger recorded." }, "chainClass": { "type": "string", "description": "Chain of the recorded address (\"evm\", \"solana\", …)." }, "occurredAt": { "type": "string", "format": "date-time", "description": "When the screening decision was made. For a user-added result, the time\nthe user gave (the time it was added when none was given); for the\ncreation entry of a Case opened by hand, the Case's creation time." }, "payloadSha256": { "type": "string", "description": "Hex SHA-256 of the canonical source payload." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the Trigger was recorded on the Case." } }, "description": "TriggerProvenance is the immutable record of the event behind one entry of\na Case's Screening history: the screening hit, the result a user recorded,\nor the by-hand creation of the Case. The original event payload stays\nserver-side; payloadSha256 is its integrity fingerprint." } } } } ```