API Reference · v1

Card IV Compliance Engine · HTTPS API

Programmatic access to the FHWA HDS-5 compliance engine that drives Card IV Compliance Validation. Built for firms with an existing ArcGIS Field Maps or Survey123 workflow that want defensible pass/fail + PDF output without rebuilding the hydraulics in-house.

Overview

The API mirrors the browser card: same engine, same jurisdictions, same criteria evaluators, same PDF report generator. It is scoped narrowly: four endpoints, JSON in, JSON or PDF out. There is no state to manage on your side beyond your API key.

Status: v1 is production-shape but pre-launch. Endpoints and response shape are stable. Metered billing wiring is deferred until a Stripe account is provisioned. During this window, calls are logged but not billed.

What's supported today

Jurisdictional criteria sets

Key	Name	Criteria checked	Default storm
`hds5_generic`	HDS-5 Generic	HDS-5 capacity (HW/D)	25-yr, HW/D ≤ 1.5
`wsdot_aop`	WSDOT AOP (Fish Passage)	Capacity + bankfull + embedment + substrate	100-yr, HW/D ≤ 1.5
`wdfw`	WDFW Water Crossings	Capacity + stream simulation summary	100-yr, HW/D ≤ 1.5
`ms4`	MS4 Permit (Generic)	HDS-5 capacity (HW/D)	25-yr, HW/D ≤ 1.5

Culvert geometry, inlets, storms

Circular single-barrel culverts (any Manning n). Diameter validated across ~0.5 to 15 ft.
Six inlet types: square_edge, groove_end, projecting, mitered, beveled_45, beveled_33 (FHWA HDS-5 Chart 1 coefficients).
Four design return periods: 10, 25, 50, 100 years.
Engine: FHWA HDS-5 (3rd ed., 2012). Inlet control per Appendix A (Equations A.2 unsubmerged + A.3 submerged with slope correction). Outlet control via energy equation with entrance, friction, and exit losses.

Known limits

Documented here so you can self-select before integrating. If any of these blocks your use case, jump to the feature request section below and tell us. Prioritization is driven by pilot feedback.

Geometry not yet supported

Box culverts (FHWA Chart 8 coefficients not implemented)
Arch, pipe-arch, and elliptical culverts
Multi-barrel installations (single barrel only; call the API once per barrel as a proxy)
Skewed inlets (engine assumes a headwall perpendicular to flow)
Custom inlet coefficients (K, M, c, Y overrides not exposed via the API)

Hydrology and design flow

You supply discharge_cfs. The API validates a design flow; it does not compute one.
No built-in Rational Method calculator on the API (available on the browser card).
No IDF curve lookup, no NOAA Atlas 14 or USGS StreamStats integration yet.
Adjacent-storm capacity check uses a log-linear scaling placeholder from the design flow. Refine with regional peak-flow data for high-stakes decisions.
Steady-state peak flow only. No unsteady analysis, hydrograph routing, or dam-break scenarios.

Jurisdictional gaps

MS4 support is generic (HDS-5 capacity only). State-specific frameworks (Washington Ecology SWMMWW, Oregon DEQ, California SWRCB, etc.) are not distinguished.
No FEMA HEC-RAS floodplain criteria, CalTrans, ODOT, county-specific standards, tribal AOP programs, or non-US frameworks yet.
Custom / firm-specific criteria sets on request via the section below.

Fish passage detail

WSDOT AOP substrate check is boolean (present/absent). No D₅₀/D₈₄ grading or gradation curves.
WDFW stream simulation is a geometric summary (bankfull, embedment). Full stream-simulation design (grade control, roughness matching, water-surface profile through the crossing) is not modeled.
No fish-species-specific criteria (chinook vs. steelhead vs. cutthroat). AOP criteria treat "fish passage" uniformly.

Reporting

PDF report ships with the 104Engineering masthead; firm white-labeling not yet supported.
No photo attachments in the report.
No lat/lon or map inclusion.
Report carries a signature line for a PE to physically or digitally sign. In-app stamping / notarization is not built.

Integration surface

Request/response only. No webhooks / push notifications.
One culvert per request. No batch endpoint (loop client-side for portfolio work).
Auth is X-API-Key header only. HMAC request signing and OAuth 2.0 are deferred until an enterprise client asks.
Idempotency via X-Request-Id is supported on /compliance-check only (not on /compliance-check/report). Cache the JSON call and re-render the PDF client-side if idempotent retries matter.

Operational

Beta: no formal SLA. Post-beta target is 99.5%.
No public status page yet. /api/v1/health is the uptime primitive for your monitoring dashboard.
Usage is logged in api_call_log but not billed during beta.

The full API reference is available to signed-in users

Start a free demo, no account required, to read more details about the API reference and documentation.

Try Demo Sign in

Request a feature, jurisdiction, or fix

The scope above is what I've built so far as a solo developer. Feedback is what shapes the next release. If something on the "known limits" list blocks your work, or you need a jurisdiction / inlet type / integration I have not built yet, tell me. Every real pilot request gets triaged and answered.

Popular request categories (each button pre-fills the form with a structured template you can edit):

Responses land in the same inbox as pilot access requests. Typical turnaround is 24-72 hours during beta.

Contact for API access

Self-service key issuance is coming. During the Pioneer phase, keys are provisioned by request. Reach out and we will set up a trial key.