Developers
A FOIA pipeline you can put behind your own buttons.
Reading the archive needs no key. Writes run on Aletheca with the reader’s Thaumatica session, and partner attribution is accepted only through a signed handoff issued during onboarding.
Start here
Every read endpoint is open. This is a deliberate position rather than an oversight: an archive that publishes documents and then locks its metadata behind an API key has not really published anything, and the fee-waiver argument that makes the whole operation viable rests on the claim that everything we receive is genuinely free to the public.
curl https://aletheca.com/api/v1/requests?disposition=glomar curl https://aletheca.com/api/v1/agencies/nro
Write access
Today a partner links or embeds the hosted composer with an Aletheca-signed handoff token. The reader signs in on Thaumatica, reviews the draft, and authorises any payment on Aletheca. Editable partner slugs are not accepted as attribution.
<script src="https://aletheca.com/embed/v1.js" data-partner-token="<issued by Aletheca>" async></script> <div data-aletheca="request-button" data-agency="faa" data-label="Request the records"></div>
Resources
Read the archive
No key, no signup, no rate limit worth mentioning. Everything the website shows a visitor is available as JSON, because an archive that publishes documents and hides its metadata behind a key has not really published anything.
- GET/api/v1/requestsEvery filed request, filtered.public
- GET/api/v1/requests/{id}One request with its cost, correspondence and documents.public
- GET/api/v1/requests/{id}/eventsThe full public ledger for one request.public
- GET/api/v1/eventsThe firehose — every public event, newest first.public
- GET/api/v1/documentsReleased documents with pages, exemptions and OCR state.public
- GET/api/v1/documents/{id}/fileStream an ingested public source file, with range support.public
- GET/api/v1/agenciesThe register — 1,380 federal, state and international bodies with statute, deadline and intake routes. jurisdiction is federal|state|foreign; country filters the international layer by ISO code.public
- GET/api/v1/agencies/{slug}One body: register entry, components, and a scorecard where Aletheca has filed.public
- GET/api/v1/lawsAll 74 statutes — 58 US public-records laws plus 16 international FOI regimes — with deadlines, appeal paths and fee-waiver standards.public
- GET/api/v1/laws/{id}One statute in full, with the bodies that answer to it.public
- GET/api/v1/coverageWhat Aletheca can file against, with the confidence of each layer.public
- GET/api/v1/jurisdictionsLocal governments — 52,105 counties, municipalities, townships and school districts, named from Census files.public
- GET/api/v1/jurisdictions/{state}/{geoid}One local government: classification, governing statute, and the offices that hold records.public
- GET/api/v1/docketOpen proposals with votes, funding and quorum.public
- GET/api/v1/dispositionsThe controlled vocabulary, with tones and clock semantics.public
Hosted actions
These routes use the reader's Thaumatica session. Partner attribution is accepted only through an Aletheca-signed handoff token; an editable partner slug is ignored.
- POST/api/v1/proposalsSave one or more tailored proposals to the Docket.member session
- POST/api/v1/requestsSave one or more tailored commissions for review; no charge or dispatch occurs here.member session
- POST/api/v1/requests/{id}/checkoutOpen Stripe Checkout for an owned, reviewed commission quote.member session
- POST/api/v1/checkouts/fundingOpen Stripe Checkout for a proposal or campaign contribution.member session
Write boundary
A composer POST saves a draft for review. It does not charge or dispatch. Checkout and the signed Stripe webhook are separate, visible state transitions.
Pagination
Cursor-based. `next` is an opaque string; pass it back as `cursor`. Offsets would drift as the ledger grows, which on a feed that appends constantly is a guarantee of missed rows.
Versioning
The path carries the major version. Fields are added without a bump; a field is never removed or re-meant inside a version.
Partner boundary
Partner API keys, outgoing partner webhooks, and the partner payout ledger are not mounted yet. They are not listed in discovery and should not be built against. The available contract is the public read API plus the signed hosted handoff; revenue share terms remain an onboarding agreement until the ledger ships.