# samgovapi.io API reference

Independent API, public lookup pages and MCP server for U.S. federal contracting data: SAM.gov entities (UEI, CAGE, registration status and expiry, NAICS), contract opportunities, exclusions, and USAspending contract awards. Every record links to its SAM.gov or USAspending source.

Independent. Not affiliated with, endorsed by or sponsored by GSA, SAM.gov or any U.S. government agency. Registering in SAM.gov is free at sam.gov.

Base URL: https://samgovapi.io/api/v1 . Auth: Authorization: Bearer <key>. OpenAPI: https://samgovapi.io/openapi.json . MCP: https://samgovapi.io/api/mcp

Every success answers {"data": ..., "meta": {"source", "as_of", "credits_charged", "next_cursor"}}. Errors answer {"error": {"code", "message"}} and cost nothing.

## Endpoints

| Method | Path | What it answers | Credits | MCP tool |
| --- | --- | --- | --- | --- |
| GET | /api/v1/entities | Search registered entities by name, NAICS, PSC, state, set-aside, status or expiry window | search | search_entities |
| GET | /api/v1/entities/{uei} | One entity by UEI: registration, expiry, NAICS, PSC, SBA certifications, exclusion flag | lookup | get_entity |
| GET | /api/v1/entities/{uei}/awards | Award history for one entity (3x credits) | history | search_awards |
| GET | /api/v1/cage/{cage} | One entity by CAGE code | lookup | get_entity |
| GET | /api/v1/registration-status/{id} | Is this UEI or CAGE registered, when does it expire, is it excluded | lookup | registration_status |
| GET | /api/v1/opportunities | Search contract opportunities by keyword, NAICS, PSC, set-aside, agency, state, type and dates | search | search_opportunities |
| GET | /api/v1/opportunities/{notice_id} | One opportunity with its full description; contracting-officer contacts as printed in the notice on Pro and Scale | lookup | get_opportunity |
| GET | /api/v1/exclusions | Search exclusion records of firms, vessels and special entities | search | - |
| GET | /api/v1/exclusions/check | Is this UEI, CAGE or exact name actively excluded | lookup | exclusion_check |
| GET | /api/v1/exclusions/{id} | One exclusion record | lookup | - |
| GET | /api/v1/awards | Search contract awards by recipient, agency, NAICS, PSC, vehicle, fiscal year or end date | search | search_awards |
| GET | /api/v1/awards/{id} | One award by USAspending award id or PIID | lookup | - |
| GET | /api/v1/recompetes | Awards whose potential end date falls in the next months: likely recompetes | search | recompetes |
| GET | /api/v1/naics | Search NAICS codes by code prefix or title words | search | naics_lookup |
| GET | /api/v1/naics/{code} | One NAICS code with title, description and SBA size standard | lookup | naics_lookup |
| GET | /api/v1/naics/{code}/size-standard | The SBA size standard for a code, and whether given receipts or employees count as small | lookup | size_standard_check |
| GET | /api/v1/psc | Search product and service codes | search | - |
| GET | /api/v1/psc/{code} | One product and service code | lookup | - |
| GET | /api/v1/labor-rates | GSA schedule labor rates by category, schedule, education and experience | search | labor_rates |
| GET | /api/v1/labor-rates/stats | Count, min, quartiles and max hourly rate for a labor category | lookup | labor_rates |
| GET | /api/v1/agencies | Agencies and sub-agencies | search | - |
| GET | /api/v1/agencies/{slug} | One agency with active opportunity and award counts | lookup | - |
| GET | /api/v1/datasets/status | Source date, refresh time and row count of every dataset | lookup | - |
| GET | /api/v1/teaming-partners | Active, unexcluded firms in a NAICS code for teaming (Pro and Scale) (Pro and Scale) | search | - |
| GET | /api/v1/export/{dataset} | Bulk CSV export of entities, opportunities, awards or exclusions (Scale; 10 credits per 1,000 rows) (Scale) | bulk | - |
| GET | /api/v1/webhooks | Your webhook endpoints (Scale) (Scale) | 0 | - |
| POST | /api/v1/webhooks | Add a signed webhook endpoint for alert events (Scale). The signing secret is shown once (Scale) | 0 | - |
| DELETE | /api/v1/webhooks/{id} | Remove a webhook endpoint (Scale) | 0 | - |
| GET | /api/v1/agent/signup | How an agent gets a key for its user, as JSON | 0 | start_signup |
| POST | /api/v1/agent/signup | Start an agent signup: returns a device code and an approval link for the person | 0 | start_signup |
| POST | /api/v1/agent/token | Poll with the device code; returns the API key once the person approves | 0 | finish_signup |
| GET | /api/v1/feedback | The feedback fields, as JSON | 0 | give_feedback |
| POST | /api/v1/feedback | Report wrong or missing data, a bug or a docs gap, or rate a result 1 to 5. No key needed, no credits | 0 | give_feedback |

`*` marks a required parameter.

### GET /api/v1/entities

Search registered entities by name, NAICS, PSC, state, set-aside, status or expiry window.

- q: Legal or DBA name, UEI or CAGE.
- naics: 6-digit NAICS code the entity lists.
- psc: PSC code the entity lists.
- state: 2-letter state of the physical address.
- set_aside: Business type or SBA program code, such as 8A or A2.
- business_type: SAM.gov business type code.
- status: active or expired.
- expiring_within_days: Registrations that expire within this many days.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/entities/{uei}

One entity by UEI: registration, expiry, NAICS, PSC, SBA certifications, exclusion flag.

- uei (required): 12-character Unique Entity ID.

### GET /api/v1/entities/{uei}/awards

Award history for one entity (3x credits).

- uei (required): 12-character Unique Entity ID.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/cage/{cage}

One entity by CAGE code.

- cage (required): 5-character CAGE code.

### GET /api/v1/registration-status/{id}

Is this UEI or CAGE registered, when does it expire, is it excluded.

- id (required): UEI or CAGE code.

### GET /api/v1/opportunities

Search contract opportunities by keyword, NAICS, PSC, set-aside, agency, state, type and dates.

- q: Words in the title or the solicitation number.
- naics: NAICS code or prefix.
- psc: PSC code.
- set_aside: Set-aside code, such as SBA, 8A, WOSB or SDVOSBC.
- agency: Department or sub-tier name.
- state: Place of performance state.
- type: Notice type, such as Solicitation.
- posted_from: YYYY-MM-DD.
- posted_to: YYYY-MM-DD.
- deadline_from: Response deadline on or after, YYYY-MM-DD.
- active: true for open notices only.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/opportunities/{notice_id}

One opportunity with its full description; contracting-officer contacts as printed in the notice on Pro and Scale.

- notice_id (required): SAM.gov notice ID.

### GET /api/v1/exclusions

Search exclusion records of firms, vessels and special entities.

- q: Name contains.
- uei: UEI.
- cage: CAGE code.
- classification: Firm, Vessel or Special Entity Designation.
- active: true for active exclusions only.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/exclusions/check

Is this UEI, CAGE or exact name actively excluded.

- q (required): UEI, CAGE or exact name.

### GET /api/v1/exclusions/{id}

One exclusion record.

- id (required): Exclusion record id from a search.

### GET /api/v1/awards

Search contract awards by recipient, agency, NAICS, PSC, vehicle, fiscal year or end date.

- recipient_uei: Recipient UEI.
- agency: Awarding agency or sub-agency name.
- naics: NAICS code or prefix.
- psc: PSC code.
- vehicle: Contract vehicle name.
- fiscal_year: Fiscal year.
- expiring_within_days: Potential end date within this many days.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/awards/{id}

One award by USAspending award id or PIID.

- id (required): USAspending generated award id or PIID.

### GET /api/v1/recompetes

Awards whose potential end date falls in the next months: likely recompetes.

- naics: NAICS code or prefix.
- agency: Awarding agency name.
- months_ahead: 1 to 36. Default 12.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/naics

Search NAICS codes by code prefix or title words.

- q (required): Code prefix or words.
- limit: 1 to 100.

### GET /api/v1/naics/{code}

One NAICS code with title, description and SBA size standard.

- code (required): NAICS code.

### GET /api/v1/naics/{code}/size-standard

The SBA size standard for a code, and whether given receipts or employees count as small.

- code (required): 6-digit NAICS code.
- revenue_usd: Average annual receipts in dollars.
- employees: Average employees.

### GET /api/v1/psc

Search product and service codes.

- q (required): Code prefix or words.
- limit: 1 to 100.

### GET /api/v1/psc/{code}

One product and service code.

- code (required): PSC code.

### GET /api/v1/labor-rates

GSA schedule labor rates by category, schedule, education and experience.

- q (required): Labor category words.
- schedule: Schedule name.
- education: Minimum education.
- min_years: Minimum years of experience.
- limit: 1 to 100.

### GET /api/v1/labor-rates/stats

Count, min, quartiles and max hourly rate for a labor category.

- q (required): Labor category words.

### GET /api/v1/agencies/{slug}

One agency with active opportunity and award counts.

- slug (required): Agency slug or code.

### GET /api/v1/teaming-partners

Active, unexcluded firms in a NAICS code for teaming (Pro and Scale).

- naics (required): 6-digit NAICS code.
- set_aside: SBA program or business type code.
- state: 2-letter state.
- limit: Rows to return, 1 to 100. Default 25.
- cursor: next_cursor from the previous page.

### GET /api/v1/export/{dataset}

Bulk CSV export of entities, opportunities, awards or exclusions (Scale; 10 credits per 1,000 rows).

- dataset (required): entities, opportunities, awards or exclusions.
- naics: Filter by NAICS code or prefix.
- state: Filter by state.
- limit: Rows, 1 to 10000. Default 1000.
- cursor: next_cursor from the X-Next-Cursor header.

### DELETE /api/v1/webhooks/{id}

Remove a webhook endpoint.

- id (required): Webhook endpoint id.

## Python

```python
import os, requests

r = requests.get(
    "https://samgovapi.io/api/v1/opportunities",
    params={"naics": "541512", "active": "true", "limit": 10},
    headers={"Authorization": f"Bearer {os.environ['SAMGOVAPI_API_KEY']}", "X-User-Request": "open IT services bids"},
)
for o in r.json()["data"]:
    print(o["notice_id"], o["title"], o["response_deadline"])
```


Get a free API key: https://samgovapi.io/sign-up?ref=ai-claudebot