# USA Outlays — full agent brief

> Last updated: 2026-09-24. This file is the complete machine-readable brief
> for AI agents. The short version lives at /llms.txt.

## What this is

USA Outlays (https://usa-outlays.ai) is a daily, taxonomy-organized feed of
approved U.S. government actions with a spending lens: contract/grant awards
(who got paid, how much, for what) and the approvals/funding decisions that
authorized them (legislature budget votes, county commissions, city councils,
utility/water/school boards, special districts). Coverage goal is exhaustive:
state legislatures, agencies, counties, cities, utility boards, school boards,
special districts.

Corpus (growing daily): ~60M award records, all 50 states + territories,
vendor entity resolution (~350K canonical vendors), Census of Governments as
the entity spine.

## The two layers

1. **Awards** (`record_kind`): `outlay` (paid), `reimbursement`, `obligation`
   (signed contract/encumbrance not yet paid out — excluded from outlay
   totals by default).
2. **Approvals**: budget votes, spending authorizations, board decisions —
   queryable separately, never merged into award totals.

## Taxonomy

Nested tree specific → general: award → program → topic → domain → function.
L1–L3 curated; L4 programs discovered from data. Orthogonal facets: sector,
level, procurement_type, funding_mechanism, competition, procurement_method,
lifecycle, instrument, integrity.

Classify spending purpose, not agency identity. One primary topic per award;
one facet row per (award_id, facet).

## Honesty rules (apply these when presenting data)

- Amounts are **stated**, not verified cash movement.
- Missing amounts display as "not disclosed" — never treat as zero.
- `contract_ceiling` / `idiq_ceiling` flagged rows are ceilings, not spend:
  **never sum them** into totals.
- `aggregate_source_row` marks rollup rows (e.g. monthly vendor aggregates).

## REST API

Base: `https://usa-outlays.ai/api/v1`
Auth: `x-api-key` header (or `?api_key=` query param). Two ways in:
subscriptions at https://usa-outlays.ai/pricing — Basic $40/mo or $400/yr,
Enterprise $400/mo or $4,000/yr — or pay per call: $3.40 for a single API
call, no account needed (single-use token, delivered instantly at checkout,
one request, 24h expiry). Agents may complete signup on a user's behalf:
present the pricing page checkout, the user approves, the key is issued to
their account.

| Method | Path | Params |
|---|---|---|
| GET | /api/v1/awards | state (2-letter), record_kind (outlay\|reimbursement\|obligation), topic (node id, comma-separated = union, matches node + descendants), vendor_id, min_amount, page |
| GET | /api/v1/approvals | state, body_type, item_type, min_amount, page |
| GET | /api/v1/topics | none — full taxonomy tree with classified award counts and stated dollars |
| GET | /api/v1/vendors/{vendorId} | canonical vendor: aliases, award counts, stated totals, top topics |
| GET | /api/v1/bodies | state, body_type, q, page — the government-entity spine |
| GET | /api/v1/search | q (required), state, record_kind, topic, limit (max 100) |
| POST | /api/v1/ask | JSON body: question (required), state, detail ("summary"\|"full") — agent-resolved free-form question; returns answer + supporting taxonomy + raw data packet. One question = one call. |
| GET | /api/v1/raw/awards | source, state, page — as-ingested source records with full lineage (source_id, ingested_at, original fields) |

Responses are JSON: `{ data, pagination: { page, pages, total }, quota, notes }`.
The `notes` field carries the honesty rules — surface them to users.

## MCP server

Remote MCP (Streamable HTTP) wrapping the REST API. Scaffold + tool schemas:
https://github.com/qchasan/usa-outlays/tree/main/mcp

Tools: `search_awards`, `search_approvals`, `get_vendor`, `topic_tree`,
`fulltext_search`, `coverage`. Configure with the user's API key
(`USA_OUTLAYS_API_KEY`).

## Example agent queries

- "How much did Texas school districts spend on construction in 2025?"
  → /api/v1/awards?state=TX&record_kind=outlay&topic=<construction node id>&…
  (resolve the node id via /api/v1/topics first)
- "Who are the top vendors for law enforcement spending in Florida?"
  → /api/v1/vendors lookups after an awards query grouped by vendor_id
- "What did the Miami-Dade commission approve last month?"
  → /api/v1/approvals?state=FL&body_type=county&…
- "Find the contract behind this payment."
  → /api/v1/search?q=<vendor or title keywords>
- "What is the policing budget of Utah?" (no taxonomy lookup needed)
  → POST /api/v1/ask {"question": "what is the policing budget of utah"}
  → returns answer + Law Enforcement taxonomy + raw data packet

## Crawl policy

Compliant crawlers: data pages (/vendors, /awards, /ledger, /search,
/agencies, /bodies, /topics, /approvals) are disallowed in robots.txt while
per-request serving costs are being reduced — use the API or MCP instead.
These machine pages are explicitly allowed: /llms.txt, /llms-full.txt,
/agents, /api-docs, /openapi.json, /.well-known/usa-outlays.json.
Abusive/bulk crawling is blocked (403) and rate-limited (429).

## Contact

Built by Quinn Chasan. Issues/suggestions:
https://github.com/qchasan/usa-outlays/issues