Canopy API Reference
On this page
This page is the canonical entry point for canopy’s REST API surface. Each service exposes a utoipa-generated OpenAPI 3.1 document that the docs build snapshots into docs/modules/ROOT/openapi/<service>.json (committed to the repo, refreshed by cargo xtask api-docs).
Specifications
The committed snapshots live next to this docs module so they ship with every Antora build. To consume a spec interactively, paste the JSON into Swagger Editor (https://editor.swagger.io/) or load the file in Postman / Insomnia.
| Service | Spec | Service-level reference | Notes |
|---|---|---|---|
canopy-rules |
JDM ruleset evaluation. Shared by every program service. |
||
canopy-persons |
Households, persons, income / asset / expense rows. ADR-004 protected data lives here. |
||
canopy-applications |
ACA §1413 single-streamlined intake. Per-program processing deadlines. |
||
canopy-eligibility |
Orchestrator. Parallel-fans-out to program services and combines their signed determinations. |
||
canopy-enrollment |
EBT enrollment + benefit-issuance pipeline. Household-scoped issuance listing. |
||
canopy-renewals |
Certification periods, change reports, renewal scheduler. |
||
canopy-notices |
Typst-rendered NOAs. PDF-out via S3 (Garage in dev). |
||
canopy-appeals |
Fair hearings + IPV/ADH workflow. |
||
canopy-reporting |
Federal extracts (FNS-388/FNS-7176/ACF-199/ACF-196/T-MSIS/CMS-64/CMS-416). |
||
canopy-security |
ADR-014 hash-chained audit subscriber, NIST-mapped breach detection. |
||
canopy-snap |
SNAP eligibility + ABAWD + categorical eligibility + alien eligibility + IEVS verification + overpayment recovery (PAMMS 9000 / 7 CFR 273.18). |
||
canopy-tanf |
TANF eligibility + work requirements + time limits + GRG + personal-responsibility + FTI audit + overpayment recovery (42 USC 609(a)(1); 45 CFR 263.11). |
||
canopy-medicaid |
All 38 COAs (MAGI / non-MAGI / CHIP) + TMA + Express Lane + FTI audit + overpayment recovery (42 CFR 433.300). |
||
canopy-caps |
Childcare and Parent Services (Georgia CCDF) — eligibility + authorization. |
||
canopy-wic |
Special Supplemental Nutrition Program for Women, Infants, and Children — categorical + nutritional risk. |
Cross-program surfaces
Some types and endpoint shapes intentionally appear in multiple program services rather than living in a dedicated cross-program service. Per ADR-001 (program-service data isolation) the data must be isolated to each program’s database, but the types and wire shape can be shared via a workspace crate that all three program services depend on.
Currently in this pattern:
-
Overpayment recovery — shared crate
crates/canopy-overpaymentsexposes the typedOverpaymentClaim/RepaymentPlan/RecoupmentLedgerEntryshapes plus the canonical migration SQL. Each of canopy-snap / canopy-tanf / canopy-medicaid runs an identical copy of the three tables in its own database, and each exposes the same 6-endpoint surface at/v1/overpayments[/…]. canopy-reporting composes the cross-program CSV roll-up over HTTP per ADR-001 (no cross-program DB access). See the archived plan for the lifecycle and design rationale.
Pattern precedent: canopy-signing (types shared, signing keys per-service) and canopy-policy (types + tooling shared, jurisdiction.toml lives in rulesets/).
Refresh workflow
Snapshots are refreshed when contract changes are accepted:
cargo xtask dev start # bring up devstack
cargo xtask api-docs # check snapshots vs running services
cargo xtask api-docs --update # accept changes (after review)The unflagged form is wired into cargo xtask validate so contract drift surfaces as a pre-push failure. The drift gate is intentional: pre-1.0 contracts CAN change, but every change should be a deliberate snapshot bump in the same commit as the code change.
Live Swagger UI
When the devstack is running, every service exposes an interactive Swagger UI at /swagger-ui on its own host port. Look up the host port via cargo xtask dev status or .ports.env, then visit e.g. http://localhost:<port>/swagger-ui.