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
Partner earnings statements
A separate operator-issued accounting:read key can read its partner's accrued earnings and immutable adjustment history. Balances are liabilities, not payouts. Lookup and handoff keys have no statement access.
- POST/api/v1/partner/statementsSend an accounting:read Bearer key and a JSON object. Default: complete accrued_cents and up to 50 newest entries; follow next_before_sequence as before_sequence. Separate pages do not share a snapshot. Use format: snapshot for complete history, or format: period with exact UTC starts_at/ends_at for an inclusive-start/exclusive-end recording-time interval and opening/net/closing accrued balances. Downloads share one database snapshot and a SHA-256 header; each is capped at 10000 entries and 3 MiB, with 413 and no partial data on overflow. Periods are captures, not locked closes or payout receipts. Use format: approved to browse the latest 50 operator-approved statements (including superseded revisions), add capture_id for revision/head and ledger-change metadata, or also download: true for the original retained bytes and checksum. Drafts and operator audit fields stay private; exact approved IDs remain readable outside that bounded list. Opt in with history: true for 50-row history pages; follow next_before_capture_id as before_capture_id until null. Approved UUID anchors preserve the exact SQL timestamp/UUID ordering without relying on rounded public times. Pages are fresh reads, not a frozen export.scoped partner credential
Partner delivery health
Operator-managed HTTPS webhooks deliver minimal public milestones for attributed requests. Delivery requires explicit receiver registration and worker activation. A requests:read key can inspect one endpoint and exact private reference; this API does not register receivers or send messages.
- POST/api/v1/partner/deliveriesInspect delivery status for endpoint_id and external_ref using a requests:read Bearer key. Optional after_sequence is a nonnegative bigint string; pages contain up to 50 entries with a next sequence cursor.scoped partner credential
Partner hosted handoffs
A separate operator-issued handoffs:create key lets a partner server obtain a short-lived signed link to the hosted composer. The reader still signs in and submits for review; no request, payment or dispatch is created by issuing a handoff.
- POST/api/v1/partner/handoffsCreate a signed hosted handoff for one external_ref. Send a handoffs:create key in Authorization: Bearer and external_ref plus optional expires_in_seconds (60–3600, default 900) in JSON. The token expires with its key and is invalidated by key revocation.scoped partner credential
Partner reference lookup
Exact-reference lookup with a current signed handoff or operator-issued requests:read key. Keys cannot originate filings; automated payouts remain planned.
- POST/api/v1/partner/requestsResolve the authenticated partner’s exact reference to public request projections. Send the credential in Authorization: Bearer; read keys require external_ref in the JSON body.scoped partner credential
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 complete filtered public event collection, newest first. Offset cursors remain the default; pagination=keyset opts into a filter-bound timestamp/ID cursor. Keysets are live views with an upper fence, not retained snapshots; replay overlapping windows for backfills.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
Pass the opaque `next` value back as `cursor`. Request listings use live offset pages; new filings or edits can move results between pages. Refresh from the beginning for a new traversal.
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
Operator-issued read keys can resolve your own exact references to public request projections. They cannot originate or pay for a filing. Separate handoff keys create signed hosted composer links. Operator-managed webhooks deliver minimal milestones after receiver registration and worker activation; read keys inspect delivery health for one endpoint and exact reference. Prospective platform-fee accounting requires explicit operator-approved terms and verified payment totals, with refund and dispute reversals. A separate accounting:read key can read accrued earnings statements and download complete snapshots. Direct server origination, financial dashboard screens and payouts remain planned.