{"openapi":"3.1.0","info":{"title":"GovCon API","description":"\n## Federal Contracts API for Developers\n\nClean JSON access to federal procurement data: contract opportunities, awards,\nthe SAM entity registry, debarment exclusions, and contracting-officer contacts.\n\n### What's covered\n- **Contract opportunities** (SAM.gov notices, daily refresh)\n- **Award history** (winners, amounts, agencies, dates)\n- **SAM entity registry** (~873K registered firms by UEI or CAGE; registration\n  status, expiration, NAICS, business-type certifications)\n- **Exclusions** (debarred / suspended entities)\n- **Companies** (Pro: combined SAM profile + award history)\n- **Vendor Risk** (Pro: 7-signal screening per UEI)\n\n### Authentication\nAll endpoints (except public demo) require Bearer token authentication:\n```\nAuthorization: Bearer your_api_key_here\n```\n\n### Plans\n- **Free Trial**: 25 req/day, 14 days, no credit card\n- **Developer ($19/mo)**: 1000 req/hr, all opportunities + awards + exclusions\n  filters + SAM entity lookup (UEI, CAGE, name search) + CSV exports\n- **Pro ($39/mo)**: everything Developer + Companies API + multi-filter\n  entity search + SAM expiration radar + Vendor Risk + unlimited GovCon Contacts\n\nUse `/api/v1/stats` and `/api/v1/me` endpoints for current data and plan details.\n\n### 📚 Documentation\n- **This page**: Interactive API reference for developers\n- **[Comprehensive Guide](/api-guide)**: Business documentation with worked examples and use cases\n    ","contact":{"name":"GovCon API Support","url":"https://govconapi.com/"},"license":{"name":"API Terms of Service","url":"https://govconapi.com/terms"},"version":"1.0.0"},"paths":{"/dashboard":{"get":{"tags":["Admin"],"summary":"Get Dashboard Html","description":"Visual dashboard shell.\nAuthentication handled client-side via JavaScript + localStorage.","operationId":"get_dashboard_html_dashboard_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/dashboard.json":{"get":{"tags":["Admin"],"summary":"Get Dashboard Json","description":"Dashboard data as JSON - view app health, user stats, and performance metrics","operationId":"get_dashboard_json_dashboard_json_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Dashboard Json Dashboard Json Get"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/awards/search":{"get":{"tags":["Awards"],"summary":"Search Federal Contract Awards","description":"Search awarded contracts by awardee name, UEI, agency, NAICS, amount range, and date range. All filters available on all plans. Free plan: max 50 results. Paid plan: max 1000 results.","operationId":"api_search_awards_api_v1_awards_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"awardee_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Awardee company name (partial match, case-insensitive)","title":"Awardee Name"},"description":"Awardee company name (partial match, case-insensitive)"},{"name":"uei","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact UEI match","title":"Uei"},"description":"Exact UEI match"},{"name":"naics","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"NAICS code","title":"Naics"},"description":"NAICS code"},{"name":"agency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Awarding agency (partial match)","title":"Agency"},"description":"Awarding agency (partial match)"},{"name":"amount_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Minimum award amount","title":"Amount Min"},"description":"Minimum award amount"},{"name":"amount_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Maximum award amount","title":"Amount Max"},"description":"Maximum award amount"},{"name":"awarded_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Awards on or after this date (YYYY-MM-DD)","title":"Awarded After"},"description":"Awards on or after this date (YYYY-MM-DD)"},{"name":"awarded_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Awards on or before this date (YYYY-MM-DD)","title":"Awarded Before"},"description":"Awards on or before this date (YYYY-MM-DD)"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Awardee state code (2-letter, e.g. CA)","title":"State"},"description":"Awardee state code (2-letter, e.g. CA)"},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort field: award_amount, award_date, awardee_name","title":"Sort By"},"description":"Sort field: award_amount, award_date, awardee_name"},{"name":"sort_order","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Sort order: asc or desc","default":"desc","title":"Sort Order"},"description":"Sort order: asc or desc"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Results per page","default":20,"title":"Limit"},"description":"Results per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/awards/{award_number}":{"get":{"tags":["Awards"],"summary":"Get Award by Contract Number","description":"Get a single award record by award/contract number. Returns the most recent record if multiple exist.","operationId":"api_get_award_api_v1_awards__award_number__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"award_number","in":"path","required":true,"schema":{"type":"string","title":"Award Number"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/opportunities/delta":{"get":{"tags":["Delta Sync"],"summary":"Delta Sync","description":"Get all opportunities added or modified since a given timestamp. Use this to keep your local database in sync without re-pulling everything.","operationId":"api_delta_sync_api_v1_opportunities_delta_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"since","in":"query","required":true,"schema":{"type":"string","description":"ISO 8601 timestamp (e.g. 2026-04-05T06:00:00Z). Returns records where last_seen >= this value.","title":"Since"},"description":"ISO 8601 timestamp (e.g. 2026-04-05T06:00:00Z). Returns records where last_seen >= this value."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Results per page","default":1000,"title":"Limit"},"description":"Results per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/search":{"get":{"tags":["Companies (Pro)"],"summary":"Search companies by name or UEI","description":"Case-insensitive trigram search across awardee names + UEI prefix match.\n\nReturns distinct awardees ordered by total_awards desc. Paginated via\nlimit + offset. pagination.total is the full match count across all pages.","operationId":"search_companies_api_v1_companies_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Name substring or UEI prefix","title":"Q"},"description":"Name substring or UEI prefix"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{uei}":{"get":{"tags":["Companies (Pro)"],"summary":"Company profile with aggregated stats","description":"Aggregate profile for a single UEI.\n\nCombines two sources:\n  - **SAM entity registration** (legal name, DBA, address, NAICS, PSC,\n    business-type certifications, registration dates, CAGE codes)\n  - **Award history** (totals, top NAICS/agencies, activity windows)\n\nReturns 200 if either source has the UEI. Returns 404 only when the UEI\nis unknown to both. Award fields default to 0/empty when the company is\nSAM-registered but has never won a contract (the common case for SMBs\nin the SAM directory of ~880K registered entities).","operationId":"get_company_profile_api_v1_companies__uei__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"uei","in":"path","required":true,"schema":{"type":"string","title":"Uei"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{uei}/awards":{"get":{"tags":["Companies (Pro)"],"summary":"Award history for a UEI (paginated)","description":"Full paginated award history. sort=date (default, desc) | amount (desc).","operationId":"get_company_awards_api_v1_companies__uei__awards_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"uei","in":"path","required":true,"schema":{"type":"string","title":"Uei"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"sort","in":"query","required":false,"schema":{"type":"string","pattern":"^(date|amount)$","default":"date","title":"Sort"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/companies/{uei}/peers":{"get":{"tags":["Companies (Pro)"],"summary":"Similar companies by NAICS + agency overlap","description":"Find similar awardees based on overlap of NAICS codes and agencies.\n\nScoring: count NAICS overlap + count agency overlap (each weighted by\ntheir award frequency at the target UEI). Not a true Jaccard; closer\nto 'weighted match count'.\n\nThis is the slowest endpoint. Expect 200-1500ms on prod data.","operationId":"get_company_peers_api_v1_companies__uei__peers_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"uei","in":"path","required":true,"schema":{"type":"string","title":"Uei"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/vendor-risk/{uei}":{"get":{"tags":["Vendor Risk (Pro)"],"summary":"Vendor risk report for a UEI","description":"Return all seven risk signals for a single UEI.\n\nAlways returns 200 with the full signal shape, even for clean vendors.\nNever returns a risk score; callers interpret the signals themselves.","operationId":"get_vendor_risk_api_v1_vendor_risk__uei__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"uei","in":"path","required":true,"schema":{"type":"string","title":"Uei"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/vendor-risk/bulk":{"post":{"tags":["Vendor Risk (Pro)"],"summary":"Bulk vendor risk screening (up to 100 UEIs)","description":"Return risk reports for each supplied UEI. Not-found UEIs come back\nwith status='not_found' rather than failing the whole request — stale\nUEIs in vendor lists are normal.","operationId":"bulk_vendor_risk_api_v1_vendor_risk_bulk_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/entities/search":{"get":{"tags":["Entities"],"summary":"Search SAM entities (q = Developer; filters = Pro)","description":"Filter-based entity search.\n\n**Developer tier**: pass `q` only (name substring, trigram-indexed).\n\n**Pro**: combine `q` with `naics` / `state` / `business_type` /\n`active_only` filters. The DSBS replacement.\n\nAt least one of `q` / `naics` / `state` / `business_type` / `active_only`\nmust be provided. NAICS values omit the Y/N small-business suffix (we\nmatch either flag).\n\n`business_type` accepts SAM 2-3 char codes like `8W` (WOSB), `QF`\n(SDVOSB), `27` (Self-Cert SDB), `2X` (For Profit), etc. Full list in\n`entities/business_types.py`. Note: SBA-certified codes (A6, XX, JT, A4)\nare valid but appear ~zero times in the Public V2 SAM extract.","operationId":"search_entities_api_v1_entities_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":100},{"type":"null"}],"description":"Name substring (Developer tier)","title":"Q"},"description":"Name substring (Developer tier)"},{"name":"naics","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"description":"NAICS code, no Y/N suffix (Pro)","title":"Naics"},"description":"NAICS code, no Y/N suffix (Pro)"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"2-letter US state (Pro)","title":"State"},"description":"2-letter US state (Pro)"},{"name":"business_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":3},{"type":"null"}],"description":"SAM business-type code (Pro). See entities/business_types.py.","title":"Business Type"},"description":"SAM business-type code (Pro). See entities/business_types.py."},{"name":"active_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only Active registrations (Pro)","default":false,"title":"Active Only"},"description":"Only Active registrations (Pro)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/entities/expiring":{"get":{"tags":["Entities"],"summary":"Registrations expiring within N days (Pro)","description":"Active SAM registrations expiring within `within_days` days.\n\nPro. Renewal-radar use case: customers monitor a state, a NAICS\ncohort, or the full population for entities that need to renew. Past-due\nexpirations are excluded (status would already be 'E').\n\nSorted by expiration_date ascending (most urgent first). Result includes\n`days_until_expiration` for direct rendering.","operationId":"expiring_entities_api_v1_entities_expiring_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"within_days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Days from today to look ahead","default":60,"title":"Within Days"},"description":"Days from today to look ahead"},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"title":"State"}},{"name":"naics","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Naics"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/entities/by-cage/{cage_code}":{"get":{"tags":["Entities"],"summary":"SAM entity lookup by CAGE code (Developer tier)","description":"SAM-registered entity by Commercial and Government Entity (CAGE) code.\n\nCAGE is the DoD/DLA-issued 5-character identifier used by contracting\nofficers and legacy procurement systems. Each CAGE code is assigned to\none entity by DLA. Large entities (USPS, financial institutions) can\nhave multiple CAGE codes per UEI; this endpoint returns the entity\nthat owns the CAGE you queried.\n\nResponse is the same shape as `/entities/{uei}` plus a `queried_cage`\nfield echoing the input. Developer tier (matches `/entities/{uei}` —\nboth are alternate-identifier lookups for the same underlying record).","operationId":"get_entity_by_cage_api_v1_entities_by_cage__cage_code__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"cage_code","in":"path","required":true,"schema":{"type":"string","title":"Cage Code"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/entities/{uei}":{"get":{"tags":["Entities"],"summary":"SAM entity lookup by UEI (Developer tier)","description":"Single SAM-registered entity by UEI.\n\nReturns registration block (status, dates, expiring_soon flag) and entity\nblock (legal name, DBA, address, NAICS/PSC, business-type certifications,\ndecoded labels, CAGE codes).\n\nAvailable on Developer tier (any active API key). For award-history merge\non top of this data, Pro subscribers should use `/companies/{uei}`.","operationId":"get_entity_api_v1_entities__uei__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"uei","in":"path","required":true,"schema":{"type":"string","title":"Uei"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/contacts/lookup":{"get":{"tags":["Contacts (Pro)"],"summary":"Look Up Contracting Officer Contact Info","description":"Resolver lookup for a contracting officer.\n\nTwo query modes:\n- **By name** (`name=X`, optional `agency=Y` and `state=ST`). Returns up to 5 substring matches.\n- **By email** (`email=foo@bar.gov`). Exact match, single record. Useful for CRM-enrichment workflows where the email is on file and the customer wants the current name / agency / phone for that address.\n\nOne of `name` or `email` is required.\n\n**This is a resolver, not a directory.** It is not possible to list or paginate contacts via this endpoint. To browse the full directory, search by NAICS or agency, view award history, or see colleague graphs and AI dossiers, use the web app at https://contacts.govconapi.com (included with Pro).\n\n**Auth:** Pro tier ($39/mo). Returns 402 on Developer-only keys.","operationId":"lookup_contact_api_v1_contacts_lookup_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"name","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2},{"type":"null"}],"description":"Name (or partial name) of the contracting officer. Required unless `email` is provided.","title":"Name"},"description":"Name (or partial name) of the contracting officer. Required unless `email` is provided."},{"name":"agency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional agency substring for disambiguation (e.g. 'Air Force', 'DLA'). Used only with `name`.","title":"Agency"},"description":"Optional agency substring for disambiguation (e.g. 'Air Force', 'DLA'). Used only with `name`."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional 2-letter state/territory code (e.g. 'CA', 'DC'). Used only with `name`.","title":"State"},"description":"Optional 2-letter state/territory code (e.g. 'CA', 'DC'). Used only with `name`."},{"name":"email","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact email address for reverse lookup. Returns one record. Mutually exclusive with `name` (if both, `email` wins).","title":"Email"},"description":"Exact email address for reverse lookup. Returns one record. Mutually exclusive with `name` (if both, `email` wins)."}],"responses":{"200":{"description":"Up to 5 contacts matching the query.","content":{"application/json":{"schema":{}}}},"402":{"description":"Caller's plan does not include contacts_access. Upgrade to Pro."},"404":{"description":"No matching contacts."},"422":{"description":"Required parameter missing or invalid."},"429":{"description":"Rate limit exceeded."},"503":{"description":"Contacts data store temporarily unavailable. Retry."}}}},"/api/v1/opportunities/search":{"get":{"tags":["Search"],"summary":"Search Contract Opportunities","description":"Search federal contract opportunities. Free plan: basic filters. Developer plan: all filters + CSV export.","operationId":"api_search_opportunities_api_v1_opportunities_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"naics","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics"}},{"name":"psc","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psc"}},{"name":"agency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agency"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},{"name":"posted_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Posted After"}},{"name":"due_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due Before"}},{"name":"due_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Due After"}},{"name":"keywords","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Full-text search across title, agency name, and contract description. Also matches solicitation number.","title":"Keywords"},"description":"Full-text search across title, agency name, and contract description. Also matches solicitation number."},{"name":"set_aside","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Aside"}},{"name":"notice_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice Type"}},{"name":"solicitation_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Exact solicitation number (e.g., USCA25Q0053)","title":"Solicitation Number"},"description":"Exact solicitation number (e.g., USCA25Q0053)"},{"name":"value_min","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Min"}},{"name":"value_max","in":"query","required":false,"schema":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Max"}},{"name":"location","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Location"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date From"}},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Date To"}},{"name":"sort_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sort By"}},{"name":"sort_order","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"default":"desc","title":"Sort Order"}},{"name":"naics_multiple","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics Multiple"}},{"name":"has_attachments","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Attachments"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Results per page (1-1000, plan-capped further). Use Query so 0/negative reject at validator instead of returning empty data.","default":20,"title":"Limit"},"description":"Results per page (1-1000, plan-capped further). Use Query so 0/negative reject at validator instead of returning empty data."},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"},{"name":"format","in":"query","required":false,"schema":{"type":"string","default":"json","title":"Format"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/demo/opportunities":{"get":{"summary":"Demo Opportunities","description":"Public demo endpoint - returns latest 2 opportunities (cached for 6 hours)","operationId":"demo_opportunities_demo_opportunities_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/agency-crosswalk":{"get":{"summary":"Get Agency Crosswalk","description":"Public endpoint - returns agency name standardization mappings (pre-built by weekly cron)","operationId":"get_agency_crosswalk_api_agency_crosswalk_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/v1/opportunities/{notice_id}":{"get":{"tags":["Search"],"summary":"Get Single Opportunity","description":"Retrieve detailed information for a specific contract opportunity","operationId":"api_get_opportunity_api_v1_opportunities__notice_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"notice_id","in":"path","required":true,"schema":{"type":"string","title":"Notice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/opportunities/{notice_id}/attachments":{"get":{"tags":["Search"],"summary":"Get Opportunity Attachments","description":"Retrieve attachment URLs for a specific contract opportunity. Returns direct SAM.gov download links.","operationId":"api_get_attachments_api_v1_opportunities__notice_id__attachments_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"notice_id","in":"path","required":true,"schema":{"type":"string","title":"Notice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/exclusions/search":{"get":{"tags":["Exclusions"],"summary":"Search Excluded Entities","description":"Search SAM.gov exclusions database for debarred entities. Search by name, UEI, CAGE code, agency, or location.","operationId":"api_search_exclusions_api_v1_exclusions_search_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"entity_name","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Entity or person name (partial match)","title":"Entity Name"},"description":"Entity or person name (partial match)"},{"name":"uei_sam","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"UEI SAM identifier","title":"Uei Sam"},"description":"UEI SAM identifier"},{"name":"cage_code","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CAGE code","title":"Cage Code"},"description":"CAGE code"},{"name":"excluding_agency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Excluding agency code (e.g., DOJ, DOD)","title":"Excluding Agency"},"description":"Excluding agency code (e.g., DOJ, DOD)"},{"name":"classification_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Classification: Individual, Firm, Vessel, Special Entity Designation","title":"Classification Type"},"description":"Classification: Individual, Firm, Vessel, Special Entity Designation"},{"name":"exclusion_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Type: Ineligible (Proceedings Pending), Ineligible (Proceedings Completed), etc.","title":"Exclusion Type"},"description":"Type: Ineligible (Proceedings Pending), Ineligible (Proceedings Completed), etc."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"State/province code","title":"State"},"description":"State/province code"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Country code","title":"Country"},"description":"Country code"},{"name":"active_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only show currently active exclusions","default":true,"title":"Active Only"},"description":"Only show currently active exclusions"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Results per page","default":20,"title":"Limit"},"description":"Results per page"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Pagination offset","default":0,"title":"Offset"},"description":"Pagination offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/exclusions/{uei_sam}":{"get":{"tags":["Exclusions"],"summary":"Check UEI Against Exclusions List","description":"Vendor-risk screening lookup: pass a UEI SAM and find out whether that entity has an active or historical exclusion record.\n\n**Response semantics**\n- `200` — entity IS on the exclusions list. Body contains the full record.\n- `404` — UEI is **not** on the exclusions list. This is the expected answer for the vast majority of legitimate vendors and means the entity is clean.\n\n**Coverage caveat:** roughly 73% of SAM exclusions are individuals or small entities without a UEI. A 404 here means *no UEI-keyed exclusion*; to also screen against name-based debarments (e.g. principals, officers, individuals), pair this lookup with `/api/v1/exclusions/search?entity_name=...`.","operationId":"api_get_exclusion_api_v1_exclusions__uei_sam__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"uei_sam","in":"path","required":true,"schema":{"type":"string","title":"Uei Sam"}}],"responses":{"200":{"description":"Entity is on the exclusions list. Full record returned.","content":{"application/json":{"schema":{}}}},"404":{"description":"No UEI-keyed exclusion found. Entity is clean by UEI; screen names separately for full coverage."},"429":{"description":"Rate limit exceeded."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/stats":{"get":{"tags":["Public"],"summary":"Database Statistics","description":"Get current database statistics and data freshness information","operationId":"api_get_stats_api_v1_stats_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/me":{"get":{"tags":["Management"],"summary":"Current User Info","description":"Get current user's plan and account information","operationId":"get_current_user_info_api_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/keys":{"post":{"tags":["Management"],"summary":"Create API Key","description":"Create or regenerate API key. New users get free trial, existing users keep current plan.","operationId":"create_new_api_key_api_v1_keys_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/favicon.ico":{"get":{"summary":"Favicon Ico","description":"Serve favicon.ico (redirect to SVG)","operationId":"favicon_ico_favicon_ico_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api-guide":{"get":{"summary":"Api Guide","description":"Comprehensive API documentation with performance metrics and enterprise patterns","operationId":"api_guide_api_guide_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/health":{"get":{"summary":"Health","description":"Health check endpoint.","operationId":"health_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/export.csv":{"get":{"summary":"Export Csv","description":"Export opportunities as CSV. Max 1000 records. Uses same filters as search.","operationId":"export_csv_export_csv_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"keywords","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keywords"}},{"name":"naics","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics"}},{"name":"naics_multiple","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics Multiple"}},{"name":"agency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agency"}},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"}},{"name":"set_aside","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Aside"}},{"name":"notice_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice Type"}},{"name":"solicitation_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Solicitation Number"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":1000,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/checkout":{"post":{"summary":"Create Checkout Session","description":"Create Stripe checkout session for Developer plan subscription","operationId":"create_checkout_session_api_v1_checkout_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/sitemap.xml":{"get":{"summary":"Sitemap","description":"Generate XML sitemap for search engines including daily snapshots","operationId":"sitemap_sitemap_xml_get","responses":{"200":{"description":"Successful Response"}}}},"/robots.txt":{"get":{"summary":"Robots","description":"Generate robots.txt for search engine crawlers","operationId":"robots_robots_txt_get","responses":{"200":{"description":"Successful Response","content":{"text/plain":{"schema":{"type":"string"}}}}}}}},"components":{"schemas":{"BulkRequest":{"properties":{"ueis":{"items":{"type":"string"},"type":"array","maxItems":100,"minItems":1,"title":"Ueis","description":"1-100 UEIs to screen in one request"}},"type":"object","required":["ueis"],"title":"BulkRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Search","description":"Search and filter federal contract opportunities"},{"name":"Management","description":"API key and user account management"},{"name":"Public","description":"Public endpoints requiring no authentication"}]}