{"openapi":"3.0.3","info":{"title":"Gnist Context — USASpending","description":"U.S. federal spending data — contracts, grants, and agency budgets.\n\n- **MCP endpoint:** `https://context.gnist.ai/mcp/usaspending/`\n- **Toolkit page:** `/toolkits/usaspending`\n- **Full API spec:** `/api/openapi.json`\n- **Get an API key:** `/signup`","version":"1.0.0","contact":{"name":"GnistAI","url":"https://gnist.ai"}},"servers":[{"url":"https://context.gnist.ai","description":"Production"}],"paths":{"/rest/usaspending/search_awards":{"post":{"tags":["Economics"],"summary":"search_awards","description":"Search USASpending.gov for federal awards (contracts, grants, loans, direct payments).\n\nUSASpending.gov is the official source for US federal government spending data,\ncovering $6–7 trillion annually from FY2008–present, updated nightly.\n\nArgs:\n    query: Keywords to search for (e.g. \"Lockheed Martin\", \"cybersecurity\", \"COVID-19 relief\").\n    award_type: Filter by award category. Values: \"contracts\" (default), \"grants\", \"loans\",\n                \"direct_payments\".\n    agency: Filter by awarding agency name (e.g. \"Department of Defense\",\n            \"Department of Health and Human Services\").\n    date_from: Only include awards starting on or after this date (YYYY-MM-DD).\n    date_to: Only include awards starting on or before this date (YYYY-MM-DD).\n    limit: Number of results to return (1–50, default 10). Sorted by award amount descending.\n\nReturns:\n    Dict with 'count', 'has_next', and 'awards' list. Each award includes award_id,\n    recipient_name, award_amount, awarding_agency, start/end dates, description,\n    and NAICS industry classification.","operationId":"usaspending_search_awards","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"query":{"description":"Keywords to search for (e.g. \"Lockheed Martin\", \"cybersecurity\", \"COVID-19 relief\").","type":"string"},"award_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by award category. Values: \"contracts\" (default), \"grants\", \"loans\", \"direct_payments\"."},"agency":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by awarding agency name (e.g. \"Department of Defense\", \"Department of Health and Human Services\")."},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only include awards starting on or after this date (YYYY-MM-DD)."},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Only include awards starting on or before this date (YYYY-MM-DD)."},"limit":{"default":10,"description":"Number of results to return (1–50, default 10). Sorted by award amount descending.","type":"integer"}},"required":["query"],"type":"object"}}}}}},"/rest/usaspending/get_award":{"post":{"tags":["Economics"],"summary":"get_award","description":"Fetch detailed information for a specific federal award.\n\nUse the generated_internal_id from search_awards results (e.g.\n\"CONT_AWD_N0001917C0001_9700_-NONE-_-NONE-\") to look up full details including\nrecipient info, subaward data, contracting details, and place of performance.\n\nArgs:\n    award_id: The generated_unique_award_id or generated_internal_id from search results.\n\nReturns:\n    Dict with full award details: obligation amounts, recipient, agencies, NAICS/PSC codes,\n    subaward count, place of performance, and period of performance dates.","operationId":"usaspending_get_award","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"award_id":{"description":"The generated_unique_award_id or generated_internal_id from search results.","type":"string"}},"required":["award_id"],"type":"object"}}}}}},"/rest/usaspending/get_recipient":{"post":{"tags":["Economics"],"summary":"get_recipient","description":"Search for or fetch a federal award recipient (contractor, grantee, etc.).\n\nSearch by name/keyword to find recipients, or pass a recipient_id (from search_awards\nresults) to get a full profile with alternate names, business types, and location.\n\nArgs:\n    keyword: Recipient name or keyword to search (e.g. \"Raytheon\", \"Johns Hopkins\").\n    recipient_id: Specific recipient hash ID for full profile lookup\n                  (e.g. \"6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C\").\n    limit: Number of search results (1–50, default 10). Ignored when using recipient_id.\n\nReturns:\n    Dict with 'count', 'total', and 'recipients' list. Each includes name, UEI,\n    total award amount, and (for profile lookups) business types, location, and alternate names.","operationId":"usaspending_get_recipient","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"keyword":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Recipient name or keyword to search (e.g. \"Raytheon\", \"Johns Hopkins\")."},"recipient_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Specific recipient hash ID for full profile lookup (e.g. \"6cf5fb1b-4988-d087-5dc1-70939d8fc6c4-C\")."},"limit":{"default":10,"description":"Number of search results (1–50, default 10). Ignored when using recipient_id.","type":"integer"}},"type":"object"}}}}}},"/rest/usaspending/get_agency_spending":{"post":{"tags":["Economics"],"summary":"get_agency_spending","description":"Fetch budgetary resources for a US federal agency.\n\nCommon toptier agency codes:\n- \"097\" — Department of Defense\n- \"075\" — Department of Health and Human Services\n- \"012\" — Department of Agriculture\n- \"069\" — Department of Transportation\n- \"089\" — Department of Energy\n- \"028\" — Social Security Administration\n\nArgs:\n    agency_code: Three-digit toptier agency code (e.g. \"097\" for DoD).\n    fiscal_year: Federal fiscal year (Oct–Sep). Omit for most recent available.\n\nReturns:\n    Dict with toptier_code, fiscal_year, agency_budgetary_resources (total budget authority),\n    agency_total_obligated (committed), agency_total_outlayed (spent),\n    and total_budgetary_resources (all-government total for comparison).","operationId":"usaspending_get_agency_spending","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"agency_code":{"description":"Three-digit toptier agency code (e.g. \"097\" for DoD).","type":"string"},"fiscal_year":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Federal fiscal year (Oct–Sep). Omit for most recent available."}},"required":["agency_code"],"type":"object"}}}}}},"/rest/usaspending/spending_by_geography":{"post":{"tags":["Economics"],"summary":"spending_by_geography","description":"Aggregate federal spending by geographic area (state, county, or congressional district).\n\nUseful for analyzing where federal money flows — e.g. which states receive the most\ndefense contracts, or where COVID relief grants were concentrated.\n\nArgs:\n    keywords: Search terms to filter spending (e.g. [\"cybersecurity\"], [\"COVID-19\", \"relief\"]).\n    geo_layer: Geographic granularity. Values: \"state\", \"county\", \"district\"\n               (congressional district). Default \"state\".\n    scope: What location to aggregate by. Values: \"place_of_performance\" (where work happens),\n           \"recipient_location\" (where recipient is based). Default \"place_of_performance\".\n    award_type: Filter by category: \"contracts\", \"grants\", \"loans\", \"direct_payments\".\n                Omit for all types.\n    date_from: Start date filter (YYYY-MM-DD).\n    date_to: End date filter (YYYY-MM-DD).\n\nReturns:\n    Dict with 'scope', 'geo_layer', 'count', and 'results' list. Each result includes\n    shape_code (state/county/district code), display_name, aggregated_amount, population,\n    and per_capita spending.","operationId":"usaspending_spending_by_geography","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"keywords":{"description":"Search terms to filter spending (e.g. [\"cybersecurity\"], [\"COVID-19\", \"relief\"]).","items":{"type":"string"},"type":"array"},"geo_layer":{"default":"state","description":"Geographic granularity. Values: \"state\", \"county\", \"district\" (congressional district). Default \"state\".","type":"string"},"scope":{"default":"place_of_performance","description":"What location to aggregate by. Values: \"place_of_performance\" (where work happens), \"recipient_location\" (where recipient is based). Default \"place_of_performance\".","type":"string"},"award_type":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Filter by category: \"contracts\", \"grants\", \"loans\", \"direct_payments\". Omit for all types."},"date_from":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Start date filter (YYYY-MM-DD)."},"date_to":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"End date filter (YYYY-MM-DD)."}},"required":["keywords"],"type":"object"}}}}}},"/rest/usaspending/report_feedback":{"post":{"tags":["Economics"],"summary":"report_feedback","description":"Report a bug, feature request, or general feedback for this data source.\n\nUse this when something doesn't work as expected, when you'd like\na new feature, or when you have suggestions for improvement.\n\nArgs:\n    feedback: Describe the issue or suggestion.\n    feedback_type: One of 'bug', 'feature_request', or 'general'.","operationId":"usaspending_report_feedback","responses":{"200":{"description":"Successful tool call","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Server or tool not found"},"500":{"description":"Tool execution error"}},"security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"feedback":{"type":"string"},"feedback_type":{"default":"general","type":"string"}},"required":["feedback"],"type":"object"}}}}}}},"tags":[{"name":"Economics","description":"Data sources: Economics"}],"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"gnist-api-key","description":"API key passed via request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"gnist_api_key","description":"API key passed via query parameter."}}}}