{"openapi": "3.1.0","info": {"title": "USA Outlays API","version": "1.1.0","description": "A public ledger of U.S. government spending: contract/grant awards (who got paid, how much, for what) plus the approvals and funding decisions that authorized them. 60M+ records, all 50 states, one policy taxonomy.\n\nHonesty rules: amounts are stated, not verified cash movement; missing amounts are \"not disclosed\" (never zero); contract/IDIQ ceilings are flagged and excluded from spend totals \u2014 never sum them; awards and approvals are separate layers."},"servers": [{"url": "https://usa-outlays.ai/api/v1"}],"security": [{"apiKeyHeader": []},{"apiKeyQuery": []}],"paths": {"/awards": {"get": {"summary": "List awards","description": "Awards (who got paid), reimbursements, and obligations. record_kind=obligation rows are signed contracts not yet paid out \u2014 excluded from outlay totals.","operationId": "listAwards","tags": ["awards"],"parameters": [{"$ref": "#/components/parameters/State"},{"$ref": "#/components/parameters/RecordKind"},{"$ref": "#/components/parameters/Topic"},{"$ref": "#/components/parameters/VendorId"},{"$ref": "#/components/parameters/MinAmount"},{"$ref": "#/components/parameters/Page"}],"responses": {"200": {"description": "List awards results."}}}},"/approvals": {"get": {"summary": "List approvals","description": "Approvals and funding decisions \u2014 the layer that authorized spending: legislature budget votes, county/city spending decisions, utility/water/school boards, special districts.","operationId": "listApprovals","tags": ["approvals"],"parameters": [{"$ref": "#/components/parameters/State"},{"$ref": "#/components/parameters/BodyType"},{"$ref": "#/components/parameters/ItemType"},{"$ref": "#/components/parameters/MinAmount"},{"$ref": "#/components/parameters/Page"}],"responses": {"200": {"description": "List approvals results."}}}},"/topics": {"get": {"summary": "Get taxonomy tree","description": "Taxonomy tree: government functions \u2192 domains \u2192 topics, with classified award counts and stated dollars. Resolve topic node ids here before filtering /awards by topic.","operationId": "getTopicTree","tags": ["topics"],"parameters": [],"responses": {"200": {"description": "Get taxonomy tree results."}}}},"/vendors/{vendorId}": {"get": {"summary": "Get vendor","description": "Canonical vendor entity: aliases, award counts, stated totals, top topics.","operationId": "getVendor","tags": ["vendors"],"parameters": [{"name": "vendorId","in": "path","required": true,"schema": {"type": "string"}}],"responses": {"200": {"description": "Vendor entity."}}}},"/bodies": {"get": {"summary": "List government bodies","description": "Government bodies \u2014 the entity spine (Census of Governments).","operationId": "listBodies","tags": ["bodies"],"parameters": [{"$ref": "#/components/parameters/State"},{"$ref": "#/components/parameters/BodyType"},{"$ref": "#/components/parameters/Q"},{"$ref": "#/components/parameters/Page"}],"responses": {"200": {"description": "List government bodies results."}}}},"/search": {"get": {"summary": "Full-text search","description": "Full-text search across approvals, awards, and obligations.","operationId": "fulltextSearch","tags": ["search"],"parameters": [{"name": "q","in": "query","description": "Query.","schema": {"type": "string"},"required": true},{"$ref": "#/components/parameters/State"},{"$ref": "#/components/parameters/RecordKind"},{"$ref": "#/components/parameters/Topic"},{"$ref": "#/components/parameters/Limit"}],"responses": {"200": {"description": "Full-text search results."}}}},"/ask": {"post": {"summary": "Ask a free-form question","description": "Send a plain-English question about government spending. An agent resolves it to the policy taxonomy, runs the query, and returns a summary answer plus the supporting taxonomy and a raw data packet. One question consumes one API call. Works with subscription keys and single-use per-call tokens.","operationId": "askQuestion","tags": ["ask"],"requestBody": {"required": true,"content": {"application/json": {"schema": {"type": "object","required": ["question"],"properties": {"question": {"type": "string","description": "Free-form question, e.g. 'what is the policing budget of utah'"},"state": {"type": "string","description": "Optional 2-letter state hint"},"detail": {"type": "string","enum": ["summary","full"],"default": "summary","description": "'summary' returns totals + top records; 'full' returns more records"}}}}}},"responses": {"200": {"description": "Answer with supporting taxonomy and raw data packet.","content": {"application/json": {"schema": {"type": "object","properties": {"question": {"type": "string"},"answer": {"type": "string","description": "Summary answer in plain English"},"taxonomy": {"type": "object","description": "Supporting taxonomy: topic, topic_id, topic_path, facets"},"data": {"type": "object","description": "Raw data packet: total_awards, total_amount, currency, amount_basis, records, query"},"notes": {"type": "array","items": {"type": "string"},"description": "Honesty rules applied to this answer"},"quota": {"type": "object"}}}}}}},"security": [{"apiKeyHeader": []},{"apiKeyQuery": []}]}},"/raw/awards": {"get": {"summary": "List raw as-ingested award records","description": "Award records exactly as ingested from the source, before curation and classification, with full lineage (source_id, ingested_at, original fields). Use to audit a curated number back to its source row.","operationId": "listRawAwards","tags": ["raw"],"parameters": [{"name": "source","in": "query","description": "Source id (e.g. TX-COMP)","schema": {"type": "string"}},{"$ref": "#/components/parameters/State"},{"$ref": "#/components/parameters/Page"}],"responses": {"200": {"description": "Raw award records with lineage."}},"security": [{"apiKeyHeader": []},{"apiKeyQuery": []}]}}},"components": {"parameters": {"State": {"name": "state","in": "query","description": "Two-letter state code.","schema": {"type": "string","pattern": "^[A-Z]{2}$"}},"RecordKind": {"name": "record_kind","in": "query","description": "outlay = paid; reimbursement; obligation = signed contract/encumbrance not yet paid (excluded from outlay totals).","schema": {"type": "string","enum": ["outlay","reimbursement","obligation"]}},"Topic": {"name": "topic","in": "query","description": "Taxonomy node id (comma-separated = union); matches the node and its descendants.","schema": {"type": "string"}},"VendorId": {"name": "vendor_id","in": "query","description": "Canonical vendor id.","schema": {"type": "string"}},"MinAmount": {"name": "min_amount","in": "query","description": "Minimum stated amount.","schema": {"type": "number"}},"Page": {"name": "page","in": "query","description": "Page number.","schema": {"type": "integer","default": 1,"minimum": 1}},"Q": {"name": "q","in": "query","description": "Full-text query.","schema": {"type": "string"}},"BodyType": {"name": "body_type","in": "query","description": "Government body type filter.","schema": {"type": "string"}},"ItemType": {"name": "item_type","in": "query","description": "Approval item type filter.","schema": {"type": "string"}},"Limit": {"name": "limit","in": "query","description": "Max results.","schema": {"type": "integer","default": 50,"minimum": 1,"maximum": 100}}},"schemas": {"Award": {"type": "object","properties": {"title": {"type": "string"},"vendor": {"type": "string","nullable": true},"vendor_id": {"type": "string","nullable": true},"amount": {"type": "number","nullable": true,"description": "Stated amount. Null = not disclosed, never zero."},"award_date": {"type": "string","nullable": true},"state": {"type": "string"},"record_kind": {"type": "string","enum": ["outlay","reimbursement","obligation"]}}},"Paginated": {"type": "object","properties": {"data": {"type": "array"},"pagination": {"type": "object","properties": {"page": {"type": "integer"},"pages": {"type": "integer"},"total": {"type": "integer"}}},"quota": {"type": "object"},"notes": {"type": "string","description": "Honesty rules \u2014 surface these to users."}}}},"securitySchemes": {"apiKeyHeader": {"type": "apiKey","in": "header","name": "x-api-key"},"apiKeyQuery": {"type": "apiKey","in": "query","name": "api_key"}}}}