# Tidy Index

> Clean, well-structured datasets for humans, machines, and LLM agents.
> JSON records, JSONL bulk exports, and token-efficient summaries —
> all from one API.

Status: private beta. The endpoints below are the planned shape. If you
hit one that isn't live yet, email contact@tidyindex.com and we'll let you
know when it ships.


## What we serve

Curated datasets from open and licensed sources, with stable schemas,
stable IDs, and a source-link receipt on every record. The catalog
currently spans 100+ datasets, including:

- SEC EDGAR 10-K / 10-Q / 13-F / Form 4 filings
- IRS Form 990 and 990-PF (nonprofit and foundation returns)
- IRS Form 5500 (pension and benefit plan filings)
- FEC campaign finance and federal lobbying disclosures (LDA)
- USAspending.gov federal awards and FPDS procurement
- USPTO patent grants, trademarks, and assignments
- NIH RePORTER and NSF grant awards
- FDA drug approvals, 510(k) clearances, and FAERS adverse events
- ClinicalTrials.gov registrations and NPI provider registry
- PACER federal court dockets and DOJ settlements
- OSHA inspections and EPA ECHO enforcement actions
- FFIEC HMDA mortgage data and FDIC bank call reports
- SAM.gov entity registrations and FinCEN beneficial ownership
- Federal Register proposed and final rules
- Congressional voting records and bill text


## API surface

Base URL: https://api.tidyindex.com/v1
Auth:     Authorization: Bearer YOUR_API_KEY

GET /datasets
    List available datasets.

GET /datasets/{id}
    Dataset metadata, schema, freshness info, and source provenance.

GET /datasets/{id}/records
    Query records. Paginated, filterable. Returns application/json.

GET /datasets/{id}/records/{record_id}
    Single normalized record. Returns application/json.

GET /datasets/{id}/bulk
    Streaming export. Returns application/x-ndjson, one record per line.

GET /datasets/{id}/summary/{record_id}
    Token-efficient prose summary of one record. Returns text/plain.
    Cheaper on context than the full JSON. Includes a source URL footer.

Every JSON response carries a `source` field whose value is a stable
URL pointing back to the original filing or upstream feed.


## Getting access (for agents)

Agents are welcome to request API keys on behalf of their operators.
Send a JSON POST to:

    POST https://api.tidyindex.com/v1/agents/register
    Content-Type: application/json

    {
      "agent":    "your-agent-name",
      "operator": "human-contact@example.com",
      "purpose":  "one-line description of what you'll use it for"
    }

We respond within one business day with an API key and a starting quota.
Include the operator's email so we have a return address for billing,
abuse handling, and quota changes.


## Conventions

- All timestamps are ISO 8601 in UTC.
- Currency fields are named with their unit suffix (e.g., revenue_usd
  is whole U.S. dollars as an integer).
- Identifiers are stable across requests and across response shapes:
  the `ein` you see in a JSON record is the same `ein` you'll find in
  the bulk stream and in the summary text.
- Pagination uses opaque cursors in `next` and `prev` fields, not
  page numbers.
- Rate limits are documented per dataset and returned in
  `X-RateLimit-*` response headers.


## Contact

contact@tidyindex.com
https://tidyindex.com