{"openapi":"3.0.3","info":{"title":"SearchSam Opportunities API","version":"1.0.0","description":"Search and paginate the SearchSam opportunities directory. External API calls use Authorization: Bearer <ss_live_...> and require a verified account with active Pro access. The cookie-authenticated SearchSam UI path remains supported separately."},"servers":[{"url":"/","description":"Current SearchSam deployment"}],"paths":{"/api/opportunities":{"get":{"operationId":"listOpportunities","summary":"List government contracting opportunities","description":"Returns active opportunities ordered by postedDate descending. Use a bearer API key created in SearchSam for external calls. The key must belong to a verified account with an active Pro subscription. Free accounts receive a 50-result ceiling and no agencySummary; Pro accounts receive up to 1,000 results, may receive the top-five agencySummary, and receive canonical uiLink values.","security":[{"BearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"Case-insensitive containment in title or solicitationNumber.","schema":{"type":"string"}},{"name":"department","in":"query","required":false,"description":"Case-insensitive containment in the department name.","schema":{"type":"string"}},{"name":"naics","in":"query","required":false,"description":"Repeat this parameter for each exact NAICS code to match.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string"}},"example":["541511","541512"]},{"name":"setAside","in":"query","required":false,"description":"Exact match against the set-aside code.","schema":{"type":"string"}},{"name":"state","in":"query","required":false,"description":"Case-insensitive office-state value, limited to two characters.","schema":{"type":"string","maxLength":2}},{"name":"status","in":"query","required":false,"description":"all returns every active opportunity; open means the response deadline is at least seven days away; closing means it is now through the next seven days.","schema":{"type":"string","enum":["all","open","closing"],"default":"all"}},{"name":"bookmarked","in":"query","required":false,"description":"When true, return only active opportunities bookmarked by the authenticated caller. The bookmark scope uses the caller identity from the cookie session or bearer API key; it never accepts a user ID.","schema":{"type":"boolean","default":false}},{"name":"offset","in":"query","required":false,"description":"Nonnegative integer offset. Defaults to 0 and is echoed in the response.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","required":false,"description":"Results per page. Defaults to 25 and accepts integers from 1 through 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Opportunity list and directory feed diagnostics.","headers":{"X-Request-ID":{"description":"Unique identifier for this response, also returned as requestId on HTTP errors.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SamOpportunityList"},"example":{"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"}],"agencySummary":[{"agency":"Department of Defense","count":72}],"naicsOptions":[{"code":"541511","description":"Custom computer programming services"}],"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}}}},"400":{"description":"The query parameters failed validation.","headers":{"X-Request-ID":{"description":"Unique identifier for this response, also returned as requestId on HTTP errors.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Invalid query parameters","requestId":"7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30"}}}},"401":{"description":"The bearer key is missing, malformed, unknown, or revoked.","headers":{"X-Request-ID":{"description":"Unique identifier for this response, also returned as requestId on HTTP errors.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Unauthorized","requestId":"7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30"}}}},"403":{"description":"The account is unverified or does not have active Pro access.","headers":{"X-Request-ID":{"description":"Unique identifier for this response, also returned as requestId on HTTP errors.","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"emailVerificationRequired":{"value":{"error":"email_verification_required","requestId":"7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30"}},"proRequired":{"value":{"error":"pro_required","requestId":"7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30"}}}}}},"429":{"description":"The bearer key exceeded 60 requests in its fixed 60-second window.","headers":{"X-Request-ID":{"description":"Unique identifier for this response, also returned as requestId on HTTP errors.","schema":{"type":"string","format":"uuid"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"},"example":{"code":"RATE_LIMITED","error":"Rate limit exceeded. Retry after the indicated delay.","retryAfterSeconds":30,"requestId":"7b9f4f9a-1d8e-4d0d-a7a8-9c6e2f4b1a30"}}}}}}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ss_live_...","description":"Send the API key as Authorization: Bearer ss_live_<key-secret>."}},"schemas":{"SamOpportunityItem":{"type":"object","additionalProperties":false,"required":["id","noticeId","title","solicitationNumber","department","subtierName","naicsCode","naicsDescription","typeOfSetAside","typeOfSetAsideCode","opportunityType","postedDate","responseDeadline","officeCity","officeState","active","uiLink"],"properties":{"id":{"type":"string","description":"SearchSam opportunity identifier."},"noticeId":{"type":"string","description":"SAM.gov notice identifier."},"title":{"type":"string","description":"Opportunity title."},"solicitationNumber":{"type":"string","nullable":true,"description":"Solicitation number, or null."},"department":{"type":"string","nullable":true,"description":"Parent agency, or null."},"subtierName":{"type":"string","nullable":true,"description":"Sub-tier agency, or null."},"naicsCode":{"type":"string","nullable":true,"description":"NAICS code, or null."},"naicsDescription":{"type":"string","nullable":true,"description":"NAICS description, or null."},"typeOfSetAside":{"type":"string","nullable":true,"description":"Set-aside label, or null."},"typeOfSetAsideCode":{"type":"string","nullable":true,"description":"Exact set-aside code, or null."},"opportunityType":{"type":"string","nullable":true,"description":"SAM.gov opportunity type, or null."},"postedDate":{"type":"string","format":"date-time","nullable":true,"description":"ISO timestamp, or null."},"responseDeadline":{"type":"string","format":"date-time","nullable":true,"description":"ISO timestamp, or null."},"officeCity":{"type":"string","nullable":true,"description":"Office city, or null."},"officeState":{"type":"string","nullable":true,"description":"Office state, or null."},"active":{"type":"boolean","description":"Whether the opportunity is active."},"uiLink":{"type":"string","format":"uri","nullable":true,"description":"Canonical SAM.gov link for Pro callers; null for Free callers. This field is always present."}}},"SamOpportunityAgencySummary":{"type":"object","additionalProperties":false,"required":["agency","count"],"properties":{"agency":{"type":"string","description":"Agency name."},"count":{"type":"integer","minimum":0,"description":"Number of matching opportunities."}}},"SamOpportunityNaicsOption":{"type":"object","additionalProperties":false,"required":["code","description"],"properties":{"code":{"type":"string"},"description":{"type":"string","nullable":true}}},"SamOpportunityList":{"type":"object","additionalProperties":false,"required":["items","total","offset","limit","feed"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SamOpportunityItem"}},"agencySummary":{"type":"array","description":"Optional top-five agency counts available to Pro callers.","items":{"$ref":"#/components/schemas/SamOpportunityAgencySummary"}},"naicsOptions":{"type":"array","description":"Optional active-directory NAICS facet options.","items":{"$ref":"#/components/schemas/SamOpportunityNaicsOption"}},"total":{"type":"integer","minimum":0,"description":"Total matching records, capped by access tier."},"offset":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":100},"feed":{"type":"string","enum":["OK","NEVER_SYNCED","SYNCING","SYNC_FAILED","STALE","KEY_MISSING"],"description":"Current directory feed state."},"feedErrorCode":{"type":"string","enum":["INVALID_QUERY","SYNC_NOT_READY","SYNC_STALE","SAM_API_KEY_MISSING","SAM_API_KEY_REJECTED","SAM_UPSTREAM_HTTP_ERROR","SAM_UPSTREAM_INVALID_JSON","SAM_UPSTREAM_INVALID_RESPONSE","SAM_UPSTREAM_NETWORK_ERROR","SAM_SYNC_INCOMPLETE","SAM_DIRECTORY_UNAVAILABLE","FORBIDDEN","NOT_FOUND","RATE_LIMITED"],"nullable":true,"description":"Sanitized diagnostic code when the feed is not healthy, or null."},"lastAttemptAt":{"type":"string","format":"date-time","nullable":true,"description":"Most recent sync attempt start, or null before the first attempt."},"lastCleanSync":{"type":"string","format":"date-time","nullable":true,"description":"Most recent fully successful sync, or null before the first clean sync."},"activeCount":{"type":"integer","minimum":0,"description":"Active row count while the feed is syncing or has never synced."}}},"ErrorResponse":{"type":"object","additionalProperties":false,"required":["error","requestId"],"properties":{"error":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}},"RateLimitError":{"type":"object","additionalProperties":false,"required":["code","error","retryAfterSeconds","requestId"],"properties":{"code":{"type":"string","enum":["RATE_LIMITED"]},"error":{"type":"string"},"retryAfterSeconds":{"type":"integer","minimum":1},"requestId":{"type":"string","format":"uuid"}}}}}}