REST reference
Query public records with explicit filters.
These read-only routes return public catalogue data. They don't need a company profile.
Download OpenAPI JSON. OpenAPI is a machine-readable description of routes, inputs, and responses.
Authentication and access
Use Authorization: Bearer YOUR_API_KEY. Your workspace needs an active trial or paid API plan.
Choose the key permissions listed for each dataset. Domain access settings in your workspace also apply.
Send requests from a server or a local tool that can keep your key private. This reference uses https://www.govbiz.ai.
Contract opportunities
GET /api/v2/opportunities/searchKey permission search. View coverage and sample response.
Use limit and offset. The response reports total_count.
| Parameter | Type | Limits or default |
|---|---|---|
naics_codes | array | {"type":"array","items":{"type":"string"},"default":[],"title":"Naics Codes"} |
naics_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics Code"} |
query | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for keyword","title":"Query"} |
notice_type | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notice Type"} |
state | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"State"} |
set_aside | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Aside"} |
agency_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agency Code"} |
set_aside_type | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Aside Type"} |
notice_types | array | {"type":"array","items":{"type":"string"},"default":[],"title":"Notice Types"} |
pop_state | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Place of performance state (2-letter)","title":"Pop State"} |
pop_city | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Place of performance city","title":"Pop City"} |
contracting_office_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"AAC/contracting office code e.g. FA5000","title":"Contracting Office Code"} |
installation | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Base/installation name keyword search","title":"Installation"} |
keyword | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Keyword"} |
value_min | See OpenAPI | {"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Min"} |
value_max | See OpenAPI | {"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value Max"} |
deadline_within_days | See OpenAPI | {"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"title":"Deadline Within Days"} |
posted_within_days | See OpenAPI | {"anyOf":[{"type":"integer","maximum":365,"minimum":1},{"type":"null"}],"description":"Only opportunities posted within the last N days (e.g. 7 = this week)","title":"Posted Within Days"} |
limit | integer | {"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"} |
offset | integer | {"type":"integer","minimum":0,"default":0,"title":"Offset"} |
Contract awards
GET /api/v2/contracts/searchKey permission search. View coverage and sample response.
Use limit, up to 100. Narrow results with date_from and date_to. This search has no offset parameter.
| Parameter | Type | Limits or default |
|---|---|---|
q | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Full-text search query (optional)","title":"Q"} |
query | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for q","title":"Query"} |
naics_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Naics Code"} |
agency_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agency Code"} |
set_aside | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Aside"} |
set_aside_type | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Alias for set_aside (MCP tool param name)","title":"Set Aside Type"} |
date_from | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only include awards on/after this action date (YYYY-MM-DD)","title":"Date From"} |
date_to | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only include awards on/before this action date (YYYY-MM-DD)","title":"Date To"} |
limit | integer | {"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"} |
Grant notices
GET /api/v2/grants/searchKey permission grants. View coverage and sample response.
Use limit, up to 100. This search has no offset parameter. Narrow the query with supported filters.
| Parameter | Type | Limits or default |
|---|---|---|
query | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Keyword matched against grant title/description","title":"Query"} |
agency_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Awarding agency code, e.g. HHS, USDA, ED","title":"Agency Code"} |
eligibility | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Grants.gov eligibility code. Nonprofit-relevant codes: 12 = nonprofits with 501(c)(3) status; 13 = nonprofits without 501(c)(3); 25 = other; 99 = unrestricted/open to any entity.","title":"Eligibility"} |
funding_category | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Grants.gov funding category code, e.g. ED (education), HL (health)","title":"Funding Category"} |
cfda | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Assistance Listing Number / CFDA (e.g. 93.600)","title":"Cfda"} |
status | string | {"type":"string","description":"Pipe-separated opportunity statuses: forecasted|posted|closed|archived. Default 'posted|forecasted'.","default":"posted|forecasted","title":"Status"} |
limit | integer | {"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"} |
Agency acquisition forecasts
GET /api/v2/intelligence/acquisition-forecastsKey permission intelligence. View coverage and sample response.
Use limit and offset, or the returned next_cursor.
| Parameter | Type | Limits or default |
|---|---|---|
q | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title and description search","title":"Q"} |
source_id | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Id"} |
record_type | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Record Type"} |
agency_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Agency code filter","title":"Agency Code"} |
subagency_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subagency Code"} |
contracting_office_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contracting Office Code"} |
naics_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"NAICS code filter","title":"Naics Code"} |
psc_code | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Psc Code"} |
fiscal_year | See OpenAPI | {"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Fiscal year filter","title":"Fiscal Year"} |
forecast_status | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Forecast Status"} |
set_aside_type | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Set Aside Type"} |
contract_vehicle | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Contract Vehicle"} |
solicitation_date_from | See OpenAPI | {"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Solicitation Date From"} |
solicitation_date_to | See OpenAPI | {"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Solicitation Date To"} |
award_date_from | See OpenAPI | {"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Award Date From"} |
award_date_to | See OpenAPI | {"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Award Date To"} |
value_min | See OpenAPI | {"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Value Min"} |
value_max | See OpenAPI | {"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Value Max"} |
include_inactive | boolean | {"type":"boolean","default":false,"title":"Include Inactive"} |
limit | integer | {"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"} |
offset | integer | {"type":"integer","minimum":0,"default":0,"title":"Offset"} |
cursor | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opaque pagination cursor","title":"Cursor"} |
Agency web records
GET /api/v2/intelligence/agency-web/documentsKey permission intelligence. View coverage and sample response.
Use limit and the returned next_cursor.
| Parameter | Type | Limits or default |
|---|---|---|
q | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"description":"Title and extracted-content query","title":"Q"} |
organization_id | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Organization Id"} |
source_id | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Id"} |
domain | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Domain"} |
path_prefix | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Path Prefix"} |
document_kind | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Kind"} |
active_only | boolean | {"type":"boolean","default":true,"title":"Active Only"} |
limit | integer | {"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"} |
cursor | See OpenAPI | {"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"} |
Responses and errors
Response shapes vary by endpoint. Opportunities, grants, forecasts, and web records return ok, data, and evidence fields.
Awards search returns results, query, and count. It does not return the same evidence envelope.
| Status | Meaning | Your next step |
|---|---|---|
| 400 / 422 | Invalid input | Check the filters and accepted values. |
| 401 | Missing or invalid credentials | Check your key and its active status. |
| 402 | API access is not active | Check Billing. |
| 403 | Access or permission denied | Check Billing, key scopes, and enabled domains. |
| 404 | Route or record unavailable | Check the route and record identifier. |
| 429 | Limit reached | Check usage and Retry-After when returned. |
| 502 / 503 / 504 | Source or execution unavailable | Retry with a delay. Contact support if it continues. |
Limits and request counting
REST and MCP share per-minute, daily, and calendar-month limits. Daily and monthly allowances reset at midnight UTC, the standard global time reference.
Requests admitted for execution consume allowance, even when the source returns an error. Authentication and entitlement rejections do not consume execution allowance.
Concurrency, response size, and execution time are also bounded. There are no automatic overage charges. View plan limits.
Versioning and evidence
This reference documents v2 routes. Retired v1 data routes return 410 and should not be used.
Fields may be null. Keep original source links and dates. Check source records before making decisions.