OpenAPI 3.0
AcreSeal API Documentation
REST API for HB 144 compliance automation. Integrate AcreSeal into your existing GIS, SCADA, and work management systems.
Download OpenAPI Spec (JSON)Base URL
https://acreseal.com/apiAuthentication
Authenticated endpoints require a Supabase JWT bearer token obtained via magic link login. Include in all requests:
Authorization: Bearer <your-jwt-token>Machine callers may instead present an issued API key (Bearer ak_…) scoped to the granted permissions — all read endpoints, plus job ingest with the jobs:write scope. Sealing a job stays session-only.
Webhook Signatures
Each webhook POST is signed so you can verify it originated from AcreSeal. Compute HMAC-SHA256(timestamp + "." + rawBody) with your webhook's signing secret and compare (constant-time) against the signature header. Reject stale timestamps to prevent replay.
X-AcreSeal-Webhook-Event: complaint.sealed
X-AcreSeal-Webhook-Timestamp: 1730592000
X-AcreSeal-Webhook-Signature: <hex hmac-sha256>Endpoints
| Method | Path | Description | Auth | Rate Limit |
|---|---|---|---|---|
| GET | /api/health | Platform health check | None | — |
| POST | /api/submit-complaint | Submit a landowner complaint with photo evidence and GPS | Turnstile CAPTCHA | 5/hr per IP |
| GET | /api/complaints | List complaints for your utility | Bearer JWT | 100/hr |
| GET | /api/verify-chain | Verify SHA-256 hash chain integrity for any record | None | 30/min |
| POST | /api/resolve | Submit field inspection resolution with digital signature | Bearer JWT | 10/min |
| POST | /api/export/hb144 | Generate an HB 144 complaint summary for a reporting period (PDF/CSV) | Bearer JWT | — |
| POST | /api/export/nerc-fac003 | Generate NERC FAC-003-5 vegetation compliance report | Bearer JWT | — |
| GET | /api/export/geojson | Export your pole or complaint layer as GeoJSON (RFC 7946) for ArcGIS/QGIS; complaint layer is PII-free | Bearer JWT | 3/min |
| POST | /api/integration | Webhook for external system integration (GIS, SCADA) | Bearer JWT | 100/hr |
| GET | /api/v1/carrier/claims/adjudicate/{record_id} | Adjudicate a sealed record for carrier claim review (integrity + provenance, RFC 7807 errors) | Bearer JWT | 100/min |
| POST | /api/v1/carrier/litigation/defense-package | Compile an FRE 901/902 litigation bundle for 1-50 records with a SHA-256 audit log. Carries an AcreSeal HMAC, which is an internal integrity check the recipient cannot verify | JWT / key (carrier:read) | 100/min |
| GET | /api/v1/underwriting/risk-score | k-anonymized aggregate infrastructure-risk score for a location (quantized grid, sub-counts <5 suppressed, no PII) | Bearer JWT | 100/min |
| GET | /api/v1/gis/export | Multi-format spatial export — streaming GeoJSON/KML + buffered ESRI Shapefile; layer/status/date/bbox filters, PII-free | JWT / key (gis:export) | 3/min |
| POST | /api/v1/gis/query/polygon | Query captures inside a GeoJSON polygon or corridor buffer (ST_DWithin over GIST); returns a FeatureCollection, PII-free | JWT / key (gis:export) | 3/min |
| POST | /api/v1/jobs | Create a Job/Work-Order container (optional corridor linkage: work_order_number, utility_contract_id, substation_feeder_id, corridor_span_id) for batch Merkle sealing | JWT / key (jobs:write) | 20/min |
| POST | /api/v1/jobs/{id}/attach | Attach sealed reports (UUIDv4) to a job; skips ineligible with reasons | JWT / key (jobs:write) | 20/min |
| POST | /api/v1/jobs/{id}/seal | Seal a job — RFC 6962 Merkle root + combined SHA-256 + Ed25519 signature; freezes member reports (immutable). Session JWT only — sealing is not key-authorizable. | Bearer JWT only | 20/min |
| GET | /api/v1/jobs/{id} | Job detail + independent seal verification (recomputes Merkle root, verifies Ed25519 signature) | Bearer JWT | — |
| GET | /api/v1/evidence/{record_id} | Forensic chain-of-custody report PDF (machine-generated; not an affidavit) — hashes + verification QR + photo/EXIF + Ed25519 signature | Bearer JWT | — |
| GET | /api/v1/evidence/{record_id}/certification | FRE 902(11)/(13)/(14) certification bundle PDF — cover + both certifications + hash manifest. UNEXECUTED unless a declarant is configured and the wording is counsel-reviewed | Bearer JWT | — |
| GET | /api/v1/compliance/frameworks | List registered compliance frameworks (HB 144, NERC FAC-003) with required + advisory requirements | Bearer JWT | — |
| GET | /api/v1/reports/{id}/compliance-audit | Evaluate a record against ?framework= — honest pass/fail; uncaptured rules reported INDETERMINATE, not fabricated | Bearer JWT / API key | — |
| POST | /api/v1/keys | Create an API key with read and/or jobs:write scopes; returns the full key ONCE | Bearer JWT (admin) | — |
| GET | /api/v1/keys | List this tenant's API keys (prefixes/scopes/usage — never the secret) | Bearer JWT (admin) | — |
| DELETE | /api/v1/keys/{id} | Revoke an API key (immediate) | Bearer JWT (admin) | — |
| POST | /api/v1/webhooks | Register a webhook (events: complaint.sealed, job.sealed); returns the signing secret ONCE | Bearer JWT (admin) | — |
| GET | /api/v1/webhooks | List this tenant's webhooks (URL/events/status — never the secret) | Bearer JWT (admin) | — |
| DELETE | /api/v1/webhooks/{id} | Delete a webhook (immediate; cascades its delivery log) | Bearer JWT (admin) | — |
Every record created through the API is cryptographically sealed with SHA-256 hash chains. The /verify-chain endpoint allows any third party to independently verify record integrity without authentication.
Ready to integrate?
Schedule a technical walkthrough with our team to discuss your integration requirements.
Schedule Technical Demo