Skip to main content
Baobyte AML Suite
Documentation contents

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

POST/v1/cases/{caseID}/reports

Draft a regulatory filing from a case

Required permission: reporting.report.generategenerateCaseReport

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 responses

Parameters

NameInTypeDescription
caseIDrequiredpathstring—

Responses

  • 201The generated draftReport
  • 400—
  • 404—
  • 409Linked alert or transaction evidence exceeds the synchronous complete-evidence boundary; no partial report was generated.
GET/v1/report-schemas

Installed report-schema validation provenance

Required permission: reporting.report.readlistReportSchemas

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 responses

Responses

  • 200Complete installed schema catalogueReportSchemaPage
GET/v1/reports

Regulatory reports

Required permission: reporting.report.readlistReports

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 responses

Parameters

NameInTypeDescription
kindquerySTR | CTR | SCUML | CBN_RETURN | BOARD—
statusquerydraft | validation_failed | in_review | approved | submitted | acknowledged | rejected—
case_idquerystringReturn only reports linked to this case. The filter is applied before the `(generated_at,id)` keyset boundary, so the filtered register remains resumable.
limitqueryintegerPage size, capped at 200.
cursorquerystringOpaque 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

  • 200ReportsReportPage
  • 400—
GET/v1/reports/{reportID}

A report, its rendered document and its field provenance

Required permission: reporting.report_content.readgetReport

Returns customer-level filing content, content-derived validation detail and field provenance. Filing-register permission alone is insufficient.

Show parameters and responses

Parameters

NameInTypeDescription
reportIDrequiredpathstring—

Responses

  • 200The report with its document and tracesReportDetail
  • 403—
  • 404—
POST/v1/reports/{reportID}/{action}

Review, approve, record external filing evidence or record a regulator receipt

Required permission: reporting.report.filedecideReport

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 responses

Parameters

NameInTypeDescription
reportIDrequiredpathstring—
actionrequiredpathreview | approve | record-submission | acknowledge | reject—

Responses

  • 200The report in its new stateReport
  • 400—
  • 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.
GET/v1/reports/{reportID}/export

Download the immutable rendered report payload

Required permission: reporting.report_content.readexportReport

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 responses

Parameters

NameInTypeDescription
reportIDrequiredpathstring—

Responses

  • 200Persisted filing payloadobject
  • 403—
  • 404—
GET/v1/reports/lifecycle-effects

List immutable automatic-CTR lifecycle review records

Required permission: reporting.report_content.readlistCTRLifecycleEffects

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 responses

Parameters

NameInTypeDescription
event_typequeryreversal | correction | cancellation | chargeback—
dispositionqueryno_report_impact | new_report_required | amendment_required | withdrawal_review_required | cancellation_review_required—
limitqueryintegerPage size, capped at 200.
cursorquerystringOpaque 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 firstCTRLifecycleReviewPage
  • 400—
  • 403—
GET/v1/reports/lifecycle-effects/{transactionID}

Read one immutable automatic-CTR lifecycle review record

Required permission: reporting.report_content.readgetCTRLifecycleEffect

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 responses

Parameters

NameInTypeDescription
transactionIDrequiredpathstring—
booking_tsrequiredquerystringExact booking timestamp of the lifecycle transaction, including timezone.

Responses

  • 200The immutable lifecycle review recordCTRLifecycleReviewRecord
  • 400—
  • 403—
  • 404—