Query the active federal opportunity directory from a script, internal dashboard, or data pipeline. This reference mirrors the shipped GET /api/opportunities route.
Pro access, verified identity
API-key requests require a verified user with an active Pro subscription. The key secret is shown once when you create it.
01 / Authenticate
Create an API key in the Developer API keys panel on your profile page. The full ss_live_… secret appears only once, so store it in your secret manager. Every external request sends the exact header below.
Sends a same-origin request to GET /api/opportunities. Your key is sent only in the Authorization header and is never saved or shown in the response.
02 / Request
All filters are optional. Query values are URL-encoded, and repeatable parameters such as naics appear once per value. Invalid enum values, negative offsets, or limits outside 1–100 return a 400 response.
qcloud securityCase-insensitive containment in title or solicitationNumber.
departmentDefenseCase-insensitive containment in the department name.
naics541511&naics=541512Repeat the parameter; each value matches an exact NAICS code.
setAsideSBAExact match against the set-aside code.
stateALCase-insensitive, two-character office-state value.
statusall | open | closingall is the default; open means 7+ days out; closing means now through 7 days.
bookmarkedtrue | falseWhen true, return only opportunities bookmarked by the authenticated caller.
offset0Nonnegative integer offset. Defaults to 0 and is echoed in the response.
limit25Integer from 1 to 100. Defaults to 25 and is echoed in the response.
postedDate descending. A verified Free account can access 50 results; Pro can access 1,000. The response total is capped to that caller ceiling.offset=0, then increase by the requested limit until offset >= total. Pro responses may also include a top-five agencySummary.03 / Copy and run
Copy the curl request to use this deployment's origin, and keep the key out of source control. The encoded query includes every filter family plus a repeatable NAICS parameter. Switch between representative 200 success and 400 validation-error JSON responses. Each JSON sample is a response, not a request body.
json · representative Pro response
{
"items": [
{
"id": "opp_01J8Q4FJ8Y2K",
"noticeId": "a1b2c3d4e5f6",
"title": "Cloud security operations support",
"solicitationNumber": "W52P1J-26-R-0042",
"department": "Department of Defense",
"subtierName": "Army Contracting Command",
"naicsCode": "541511",
"naicsDescription": "Custom computer programming services",
"typeOfSetAside": "Small Business",
"typeOfSetAsideCode": "SBA",
"opportunityType": "solicitation",
"postedDate": "2026-09-15T13:00:00.000Z",
"responseDeadline": "2026-10-15T17:00:00.000Z",
"officeCity": "Huntsville",
"officeState": "AL",
"active": true,
"uiLink": "https://sam.gov/opp/a1b2c3d4e5f6/view"
},
{
"id": "opp_01J8Q4G2M5LZ",
"noticeId": "f6e5d4c3b2a1",
"title": "Professional services market research",
"solicitationNumber": null,
"department": "Department of Energy",
"subtierName": null,
"naicsCode": "541618",
"naicsDescription": null,
"typeOfSetAside": null,
"typeOfSetAsideCode": null,
"opportunityType": "presolicitation",
"postedDate": "2026-09-14T09:30:00.000Z",
"responseDeadline": null,
"officeCity": null,
"officeState": "DC",
"active": true,
"uiLink": "https://sam.gov/opp/f6e5d4c3b2a1/view"
}
],
"total": 184,
"offset": 0,
"limit": 25,
"feed": "OK",
"feedErrorCode": null,
"lastAttemptAt": "2026-09-19T05:00:00.000Z",
"lastCleanSync": "2026-09-19T05:02:14.000Z",
"activeCount": 184,
"naicsOptions": [
{
"code": "541511",
"description": "Custom computer programming services"
},
{
"code": "541618",
"description": "Other management consulting services"
}
],
"agencySummary": [
{
"agency": "Department of Defense",
"count": 72
},
{
"agency": "Department of Energy",
"count": 31
}
]
}04 / Read the response
The JSON example above includes the complete envelope: items, total, offset, limit, feed diagnostics, timestamps, the active count, NAICS facet options, and the optional Pro agency summary. Nullable fields are returned as null, not omitted.
idSearchSam opportunity identifier.
noticeIdSAM.gov notice identifier.
titleOpportunity title.
solicitationNumberSolicitation number, or null.
departmentParent agency, or null.
subtierNameSub-tier agency, or null.
naicsCodeNAICS code, or null.
naicsDescriptionNAICS description, or null.
typeOfSetAsideSet-aside label, or null.
typeOfSetAsideCodeExact set-aside code, or null.
opportunityTypeSAM.gov opportunity type, or null.
postedDateISO timestamp, or null.
responseDeadlineISO timestamp, or null.
officeCityOffice city, or null.
officeStateOffice state, or null.
activeAlways true for this active directory collection.
uiLinkCanonical SAM.gov link for Pro; null for Free.
uiLink values and may receive the optional top-five agencySummary. Free callers receive uiLink: null and no agency summary.05 / Operate safely
Feed health does not change the list status code. The collection route still returns a 200 envelope when feed is one of the states below; inspect feedErrorCode for a safe diagnostic when it is present.
400 — { "error": "Invalid query parameters", "requestId": "7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30" }
401 — { "error": "Unauthorized", "requestId": "7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30" } for a malformed, unknown, or revoked bearer key.
403 — { "error": "email_verification_required", "requestId": "7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30" } or { "error": "pro_required", "requestId": "7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30" }.
429 — { "code": "RATE_LIMITED", "error": "…", "retryAfterSeconds": 12, "requestId": "7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30" } when a bearer key exceeds its request window. The response also includes a standard Retry-After header. Every response also includes an X-Request-ID header; on HTTP errors, its UUID matches the JSON requestId field for support and debugging.
Retry-After seconds. If throttled again, honor the new value or back off longer. Use bounded limits and paginate sequentially instead of fanning out page requests. Treat feed and feedErrorCode as the directory health signal.