--- title: "US securities examination readiness" method: GET path: "/api/v1/ussecurities/exam-readiness" tags: ["US Securities Compliance"] --- # US securities examination readiness `GET /api/v1/ussecurities/exam-readiness` ## Request - Base URL: `https://orchestrator.getaxonflow.com` - URL: `https://orchestrator.getaxonflow.com/api/v1/ussecurities/exam-readiness` - Auth: none declared - TypeScript: (a function with typed inputs; its response is checked against the schema) Answers "if I generate the SEC/FINRA examination package now, what will be in it and what will it have to disclose?" WITHOUT creating a report job. It returns COUNTS, PRESENCE and DISCLOSURES, never evidence rows. The rows come from the compliance report facade (`POST /api/v1/compliance/reports` with `regulator=ussecurities`) and only from there, so this is not a second export path. It exists because the facade cannot answer this question: asking it means creating a job, spending one of an Evaluation tier's three daily reports, and waiting on an async render, purely to learn whether the package is worth generating. SCOPE: the summary covers the requesting TENANCY, with two DISCLOSED exceptions rather than two silent ones (ADR-064 section 4). The RLS-gated sources - the approval queue and the signed decision chain - are additionally bounded by ORGANIZATION, because both enforce that boundary in the database. The configured supervisory controls are scoped by organization outright, because that is the scope the engine that enforces them reads them under; a tenancy-scoped inventory would publish a set of controls that is not the set being applied. The `scope` field states all three in one sentence. AUTHORITY: gated on tenant-wide read authority, the same gate as the evidence and compliance exports. It returns aggregates rather than rows, but an aggregate over `audit_logs` still describes whole-tenant activity. **Enterprise Feature**. Community builds register no route (404). ## Response `200` Examination readiness summary - USSecuritiesExamReadiness: The US securities examination-readiness summary. Counts, presence and disclosures only; it carries no evidence rows. - `tenant_id` string: The tenancy this summary covers. - `window_days` integer: The lookback the counts are taken over. One quarter, matching the sibling US modules: it is the shortest cycle any instrument in scope works to, and it bounds an unqualified read on a busy audit trail. - `period_start` string, date-time - `period_end` string, date-time - `scope` string: One sentence stating the package's tenancy boundary AND its two disclosed exceptions. Every count is meaningless without it. - `populations` USSecuritiesPopulation[]: The supervised populations and the frameworks that select each. The population is DERIVED from the framework a report requests and is never a separate request field, so a caller cannot ask for a combination that contradicts itself (ADR-063 section 2). Served so a console learns the mapping from the deployment instead of keeping a copy that drifts. - `id` 'adviser' | 'broker-dealer' | 'both' - `display_name` string - `frameworks` string[]: The framework tokens that select this population. - `recordkeeping_citation` string: States the REQUIREMENT, never this deployment's posture. Where it names WORM it also names the audit-trail alternative the 2022 amendments to Exchange Act rule 17a-4 added: naming only the first tells a firm to buy storage it may not need. - `supervision_citation` string - `marketing_citation` string: The instrument under which the firm's own AI claims are examined. This is what makes the disclosure-vs-reality reconciliation a compliance artifact rather than a marketing summary. - `sources` USSecuritiesSourceReadiness[]: Per evidence source, whether it holds anything and how much. - `key` string - `title` string - `present` boolean: An OBSERVATION, not a health check: false means the source held nothing for this tenancy in this window, which on a quiet deployment is a truthful answer and not a fault. Meaningful ONLY when `readable` is true. - `count` integer - `readable` boolean: Whether this deployment could read the source AT ALL. `present: false` has two causes needing opposite reactions - a quiet deployment, and a surface this deployment cannot read - and this is the field that separates them. A console must key on this boolean rather than on the note's prose, or rewording the sentence silently switches the warning off. - `note` string: Why the count reads as it does. Load-bearing: a note beginning `NOT REPORTED` means the generated package will carry an INCOMPLETE section, and a note beginning `DISCLOSED ABSENT` means the capability is not installed here and the section will say so rather than reporting a zero. - `instruments` USSecuritiesInstrument[]: The instruments a generated package is rendered against, each with the version or date it was read at. An instrument named without its revision leaves the reader to guess, and the guess a reader makes is always the current one. - `instrument` string - `as_of` string: The version or date this package is rendered against. - `note` string: What the instrument is cited for. - `applies_to` string[]: The registrations the instrument reaches. A rendered artifact carries only the instruments its own population appears in, because an examiner reads a citation block as the set the document answers. - `disclosures` string[]: The sentences every generated artifact carries. Returned here so nothing in a package is a surprise at the point it reaches an examiner, and served from the same source the artifact renders from, so the two cannot say different things. - `complete` boolean: False when ANY source could not be read. A package generated while this is false carries at least one INCOMPLETE section. - `fraud_risk_addon_active` boolean: Whether the Fraud and Risk Add-on's FinCrime pack was in force on at least one decision of this tenancy in the window. MEASURED from the audit trail: a decision on a scope the pack binds on records it in policy_details.policy_packs as fincrime@. The licence feature reader ADR-061 designs does not exist in the tree, and this service cannot see which packs the agent installed, so a deployment that installed the pack and made no decision in the window reads false (#4164). It is published here because the answer changes what the financial-crime section of a generated package SAYS - disclosed absent rather than empty - and an operator deciding whether to generate should see that first. - `fraud_risk_addon_decisions` integer: The number of this tenancy's decisions in the window whose audit record names the FinCrime pack. fraud_risk_addon_active is true exactly when this is above zero. - `generated_at` string, date-time ## Other responses - `401`: No organization or tenant scope on the request (`SCOPE_REQUIRED`): it did not traverse an authenticating hop. - `403`: The caller does not hold tenant-wide read authority. - `405`: Method not allowed; this route is GET-only. - `500`: The readiness summary could not be produced (`INTERNAL_ERROR`). The body carries a fixed sentence; the cause is in the orchestrator log keyed by the request. - `503`: The module is not initialized (`USSECURITIES_NOT_AVAILABLE`: the orchestrator has no database connection). A DEPLOYMENT fact, not a server fault, so it is not behind a Retry button that can never clear. --- [API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)