API reference
Reporting
8 operations in this area of the contract. Every one declares the permission it requires.
Contract version 0.2.0All areas
Operations
/v1/cases/{caseID}/reportsDraft a regulatory filing from a case
The figures are assembled from the evidence already linked to the case, not from the request body. A filing whose amounts were retyped into a form is a filing whose amounts cannot be reconciled against the transactions they came from.
The draft is validated on generation and every field records the expression that produced it. A document that fails validation is stored as `validation_failed` rather than discarded, so the failure is inspectable.
Synchronous generation is fail-closed at 200 linked alerts and 200 distinct linked transactions. Overflow returns 409 before rendering or persistence. This installation has no complete filing path for an older case above that boundary; a partial regulatory report is never generated.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
caseIDrequired | path | string | — |
Responses
201The generated draftReport400—404—409Linked alert or transaction evidence exceeds the synchronous complete-evidence boundary; no partial report was generated.
/v1/report-schemasInstalled report-schema validation provenance
Lists bounded metadata and the SHA-256 digest of each immutable schema version; it never returns the XSD body. Authoritative schemas can be activated only from a signed content pack after maker-checker approval, and only when the exact self-contained XSD compiles under the recorded validator. This release supports XSD 1.0 and deliberately refuses XSD 1.1 and `xs:include`/`xs:import`; it never resolves network or host files.
Show parameters and responsesHide parameters and responses
Responses
200Complete installed schema catalogueReportSchemaPage
/v1/reportsRegulatory reports
A bounded, keyset-resumable filing register. Every item is a `ReportSummary` limited to reference, type, lifecycle/validation state, validator identity and generation time. It never returns case or party identifiers, validation error text, actor ids, external acknowledgements, source-event keys, free-text status reasons, document or schema digests, field traces, or rendered content. Those richer fields require `reporting.report_content.read` through the report-detail endpoint.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
kind | query | STR | CTR | SCUML | CBN_RETURN | BOARD | — |
status | query | draft | validation_failed | in_review | approved | submitted | acknowledged | rejected | — |
case_id | query | string | Return only reports linked to this case. The filter is applied before the `(generated_at,id)` keyset boundary, so the filtered register remains resumable. |
limit | query | integer | Page size, capped at 200. |
cursor | query | string | Opaque keyset cursor from a previous response. Offset pagination is deliberately not offered: `OFFSET 500000` is a table scan, and if it were offered it would be used (ADR-0012). Only the collections that document this parameter can be resumed. The rest report `truncated: true` and refuse a cursor rather than silently returning the first page again — see the `truncated` field on the page schemas. |
Responses
200ReportsReportPage400—
/v1/reports/{reportID}A report, its rendered document and its field provenance
Returns customer-level filing content, content-derived validation detail and field provenance. Filing-register permission alone is insufficient.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
reportIDrequired | path | string | — |
Responses
200The report with its document and tracesReportDetail403—404—
/v1/reports/{reportID}/{action}Review, approve, record external filing evidence or record a regulator receipt
This installation has no built-in NFIU/goAML transport endpoint or credentials. Local validation and approval never claim delivery. `record-submission` is the explicit manual boundary: after an authorised user exports and files the exact bytes through the authorised external channel, they record the externally obtained reference and actual filing time. The server binds that evidence to the authenticated actor and the immutable payload/schema digests. The database refuses `submitted`, `acknowledged` and `rejected` states without matching evidence.
The legacy `submit` action is intentionally absent from the supported enum and fails closed if an older client calls it. Placeholder schemas and stale XSD proof remain independently non-fileable (Q1).
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
reportIDrequired | path | string | — |
actionrequired | path | review | approve | record-submission | acknowledge | reject | — |
Responses
200The report in its new stateReport400—409The transition is not allowed from the report's current state, or the report was generated against a non-authoritative schema, has stale validation proof, lacks immutable external filing evidence, or direct transport is unavailable.422External filing evidence is missing, malformed or inconsistent with approval time.
/v1/reports/{reportID}/exportDownload the immutable rendered report payload
Returns the bytes stored at generation time, not a document rebuilt from the current active template. `X-Content-SHA256` is the lowercase SHA-256 digest of the response. The payload contains customer-level filing content and requires the dedicated content permission; filing-register permission alone is insufficient.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
reportIDrequired | path | string | — |
Responses
200Persisted filing payloadobject403—404—
/v1/reports/lifecycle-effectsList immutable automatic-CTR lifecycle review records
A tenant-scoped, keyset-resumable operational queue for corrections, reversals, cancellations and chargebacks that affected automatic CTR reporting. Each row links the exact financial-event predecessor and the current statuses of any prior/resulting CTRs. `action_required` means an operator must follow the linked report or external amendment/withdrawal procedure; it does not claim assignment, resolution or regulator delivery. Batch-ingested and synchronous lifecycle events use the same ledger.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
event_type | query | reversal | correction | cancellation | chargeback | — |
disposition | query | no_report_impact | new_report_required | amendment_required | withdrawal_review_required | cancellation_review_required | — |
limit | query | integer | Page size, capped at 200. |
cursor | query | string | Opaque keyset cursor from a previous response. Offset pagination is deliberately not offered: `OFFSET 500000` is a table scan, and if it were offered it would be used (ADR-0012). Only the collections that document this parameter can be resumed. The rest report `truncated: true` and refuse a cursor rather than silently returning the first page again — see the `truncated` field on the page schemas. |
Responses
200Newest lifecycle review records firstCTRLifecycleReviewPage400—403—
/v1/reports/lifecycle-effects/{transactionID}Read one immutable automatic-CTR lifecycle review record
Reads the record by its exact partitioned financial-event identity. This is evidence of the reporting effect, not evidence that an external amendment or withdrawal was delivered.
Show parameters and responsesHide parameters and responses
Parameters
| Name | In | Type | Description |
|---|---|---|---|
transactionIDrequired | path | string | — |
booking_tsrequired | query | string | Exact booking timestamp of the lifecycle transaction, including timezone. |
Responses
200The immutable lifecycle review recordCTRLifecycleReviewRecord400—403—404—