Save a search
const url = 'https://api-staging.fedwright.com/v1/orgs/019aa3f2-6d10-7b20-9c4f-7e2d3cad5b12/saved-searches';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"alerting":true,"name":"Navy aircraft parts, open","query":{"facets":["setAsideProgram","department"],"filters":{"naics":["3364"],"noticeTypes":["Solicitation","Combined Synopsis/Solicitation"],"phases":["open"],"psc":["15"]},"groupByThread":true,"includeHistory":false,"q":"step assy","sort":["responseDeadline"]}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api-staging.fedwright.com/v1/orgs/019aa3f2-6d10-7b20-9c4f-7e2d3cad5b12/saved-searches \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "alerting": true, "name": "Navy aircraft parts, open", "query": { "facets": [ "setAsideProgram", "department" ], "filters": { "naics": [ "3364" ], "noticeTypes": [ "Solicitation", "Combined Synopsis/Solicitation" ], "phases": [ "open" ], "psc": [ "15" ] }, "groupByThread": true, "includeHistory": false, "q": "step assy", "sort": [ "responseDeadline" ] } }'The caller becomes the saved search’s owner.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”A UUIDv7.
The organization. The caller must be a member; otherwise the response is 404, as if it didn’t exist.
Header Parameters
Section titled “Header Parameters”A client-generated key, unique per request intent. It is scoped to the
caller (a user, machine client, or service identity) and the operation,
and to the acting organization where there is one: createOrganization
acts in none. Replays with the same key return the
original response for 24 hours after it completes.
Request Bodyrequired
Section titled “Request Bodyrequired”The request body. Unknown properties are rejected.
object
Alert on new matching notices.
Datasets included when alerting. Omit for opportunities only.
The saved search’s name, 1 to 200 characters.
The same query the search API accepts, so the saved search can be re-run exactly.
object
Facets to count over the matching notices. A combination of
requested hierarchy levels and necessary splits that needs more
than 16 queries returns 422 validation-failed at facets.
Every filter is optional. Values within one filter are alternatives (OR); different filters must all hold (AND). Free-text array items cannot contain backslashes or control characters.
object
When true, include only forecast, presolicitation, and solicitation
notices whose current response deadline is after the search time or
missing. False or absent applies no filter. Unlike the open phase,
this includes Sources Sought and Special Notices in forecast and
notices in presolicitation. A date-only deadline ends at midnight
after its date in US Eastern time.
Include only notices whose award amount is at most this amount, as a decimal string.
Include only notices whose award amount is at least this amount, as a decimal string.
Enrichment conditions.
Include only notices whose response deadline is at or after this time.
Include only notices whose response deadline is at or before this time.
Department keys.
Include only notices Fedwright first saw at or after this time. Using this filter leaves out historical notices.
Enrichment labels.
NAICS codes at any level, including range sectors such as 31-33. Older-edition codes match their current equivalents.
Include only notices of these types.
Phase is the notice’s stage: Sources Sought and Special Notices are forecast; open and closed apply only to solicitations and use the deadline at the time of the search. Use acceptingResponses to find notices that can still receive a response. archived requires includeHistory: true.
Include only notices whose place of performance is in one of these countries.
Include only notices whose place of performance is in one of these states or territories, by USPS code.
Include only notices SAM.gov posted at or after this time.
Include only notices SAM.gov posted at or before this time.
PSC codes at any level, for example 61, 6145, R, R4, or R499.
Include only notices with one of these SAM.gov set-aside codes.
Include only notices whose set-aside belongs to one of these programs.
When true, include only sole-source notices. When false, include only notices that are not sole-source.
Include only notices from these sub-tier agencies, by the name SAM.gov gives.
Opaque thread identifier; use the ID the API returns.
Return one result per thread, its best-matching notice.
Also search award notices, justifications, and archived notices.
Full-text query. Empty or missing matches every notice the filters allow. Only the first 10 words of a query are used.
How to order the results, by up to three fields, applied in order. Without it, results are ordered by relevance.
Responses
Section titled “Responses”The saved search.
A saved search: a search query kept so it can be run again and, when alerting is on, can raise alerts for new matches.
object
Alert on new matching notices.
Datasets included when alerting. Omit for opportunities only.
The saved search’s name, 1 to 200 characters.
The same query the search API accepts, so the saved search can be re-run exactly.
object
Facets to count over the matching notices. A combination of
requested hierarchy levels and necessary splits that needs more
than 16 queries returns 422 validation-failed at facets.
Every filter is optional. Values within one filter are alternatives (OR); different filters must all hold (AND). Free-text array items cannot contain backslashes or control characters.
object
When true, include only forecast, presolicitation, and solicitation
notices whose current response deadline is after the search time or
missing. False or absent applies no filter. Unlike the open phase,
this includes Sources Sought and Special Notices in forecast and
notices in presolicitation. A date-only deadline ends at midnight
after its date in US Eastern time.
Include only notices whose award amount is at most this amount, as a decimal string.
Include only notices whose award amount is at least this amount, as a decimal string.
Enrichment conditions.
Include only notices whose response deadline is at or after this time.
Include only notices whose response deadline is at or before this time.
Department keys.
Include only notices Fedwright first saw at or after this time. Using this filter leaves out historical notices.
Enrichment labels.
NAICS codes at any level, including range sectors such as 31-33. Older-edition codes match their current equivalents.
Include only notices of these types.
Phase is the notice’s stage: Sources Sought and Special Notices are forecast; open and closed apply only to solicitations and use the deadline at the time of the search. Use acceptingResponses to find notices that can still receive a response. archived requires includeHistory: true.
Include only notices whose place of performance is in one of these countries.
Include only notices whose place of performance is in one of these states or territories, by USPS code.
Include only notices SAM.gov posted at or after this time.
Include only notices SAM.gov posted at or before this time.
PSC codes at any level, for example 61, 6145, R, R4, or R499.
Include only notices with one of these SAM.gov set-aside codes.
Include only notices whose set-aside belongs to one of these programs.
When true, include only sole-source notices. When false, include only notices that are not sole-source.
Include only notices from these sub-tier agencies, by the name SAM.gov gives.
Opaque thread identifier; use the ID the API returns.
Return one result per thread, its best-matching notice.
Also search award notices, justifications, and archived notices.
Full-text query. Empty or missing matches every notice the filters allow. Only the first 10 words of a query are used.
How to order the results, by up to three fields, applied in order. Without it, results are ordered by relevance.
The codes in the query that the current reference data has retired or does not have. They are worked out on every read.
A code that the latest reference refresh retired, or no longer knows, so its owner can choose a replacement.
object
The code.
What the code is: a NAICS code, a PSC code, or a set-aside code the profile is eligible for.
retired for a retired code or one from an older edition, or unknown for a code the current reference data does not have.
When the saved search was created.
A UUIDv7.
Machine-client owner; null when a human owns the search. Exactly one owner ID is non-null.
When the saved search last changed.
Examples
A saved search
{ "alerting": true, "codeWarnings": [], "createdAt": "2026-10-02T19:01:12Z", "id": "019aa5c1-2b3c-7d4e-8f50-617283940a1b", "name": "Navy aircraft parts, open", "ownerClientId": null, "ownerUserId": "0199f0e1-3b4c-7d5e-9f60-718293a4b5c6", "query": { "facets": [ "setAsideProgram", "department" ], "filters": { "naics": [ "3364" ], "noticeTypes": [ "Solicitation", "Combined Synopsis/Solicitation" ], "phases": [ "open" ], "psc": [ "15" ] }, "groupByThread": true, "includeHistory": false, "q": "step assy", "sort": [ "responseDeadline" ] }, "updatedAt": "2026-10-02T19:01:12Z"}Headers
Section titled “Headers”Strong entity tag of the returned resource.
true when the response is a replay of the first request with this Idempotency-Key.
The URL of the created resource.
The request is malformed, or its schema refuses it: an unknown
property, a value of the wrong type or outside its bounds, a limit
above 200, or a sort outside the operation’s allow-list (Problem
type bad-request). errors names each field by its path, such as
nested.note, or $ for the body itself. The request is refused
before anything is read or written. A cursor that was altered, has
expired, or was issued for other filters, another sort, organization,
or user returns Problem type invalid-cursor.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}The access token is missing, expired, or invalid.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}The Problem type says which check refused the caller, when that is
about the caller’s own token, client, or role:
insufficient-scope when the token’s scopes (or an MCP grant’s) lack
the operation’s scope, with WWW-Authenticate: Bearer error="insufficient_scope", scope="..." (RFC 6750) naming the missing
scopes; client-not-allowed when the operation doesn’t admit the
caller’s kind of client, such as a machine client calling a user-only
operation; and insufficient-role when a confirmed member’s roles
don’t allow the action. Any other refusal is the generic forbidden,
which says nothing more. Another organization’s resource is 404
(not-found) instead, so no reason confirms that it exists. An owner
or administrator who sent no proof of a second factor gets
mfa-required. An operation
that needs an active subscription, when the organization has none,
returns subscription-inactive, or organization-suspended when
Fedwright suspended the organization. A suspended
organization also refuses invitations, new joins through an
invitation, and role changes with organization-suspended. Creating
or joining
an organization without a verified email returns email-unverified,
and accepting an invitation sent to another address returns
invitation-email-mismatch. A request from Fedwright’s web or mobile
app whose session acts for no organization yet returns
organization-required, except on getMe, createOrganization, and
acceptInvitation. Shared data needs the acting organization’s own
subscription; another organization’s doesn’t count.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}The resource does not exist, or belongs to another organization.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}The request conflicts with the resource’s current state (Problem type
conflict), such as a slug that another organization has. A retry
while the first request with its Idempotency-Key is still running
returns Problem type idempotency-in-progress, with Retry-After.
Removing the last owner, or taking the owner role from them, returns
last-owner: every organization keeps at least one owner. Inviting a
member, or an address with a pending invitation, and cancelling an
invitation whose email is still being sent, return conflict.
Starting a checkout for an organization that already has a paid
subscription returns subscription-exists. Opening the billing
portal for an organization that has never paid returns
no-billing-account.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}Headers
Section titled “Headers”Seconds to wait before retrying.
The request is well formed and its schema accepts it, but it breaks a
rule beyond the schema, such as an unknown NAICS code (Problem type
validation-failed, with errors by field path). An
Idempotency-Key already used for another request returns
idempotency-key-reused.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}A rate limit is used up. Direct API access counts against the
organization’s burst, daily, and monthly quotas, which all its machine
clients share; there is no client quota. A 429 comes in two shapes
with two header families, so read the response by what it carries.
A machine client’s calls can get a 429 with an empty body. It
has three headers: X-RateLimit-Limit, the
exhausted rule’s limit and window, such as 3000, 3000;w=2592000;
X-RateLimit-Remaining, what is left in that window (0 on a 429);
and X-RateLimit-Reset, the seconds until that window resets. It has
no Retry-After, no RateLimit headers, no Problem, and does not
name the quota. Read the quota from the window w:
w (seconds) |
Quota |
|---|---|
| 60 | Burst. |
| 86400 | Daily. |
| 2592000 | Monthly (the calendar month is reported as 30 days; X-RateLimit-Reset is exact). |
Wait X-RateLimit-Reset seconds before you retry. Refused requests
still count: a client that keeps calling after a 429 keeps adding to
the counter, so it does not regain budget inside the window. A tier
change takes effect within 10 minutes (checkout, the billing portal,
and grants alike), once the client gets a new access token.
Every other 429 has a Problem and Retry-After. The Problem type
is rate-limited for a used-up quota, or, for an ask, ai-budget-exceeded
or premium-quota-exceeded (below). On rate-limited, Retry-After is
the seconds until the used-up limit’s window resets, the latest if
several are. The Problem also carries limit, the quota that is used
up (the one that resets last, if several are), resetsAt, when it
starts again, and traceId. RateLimit-Policy and RateLimit describe only the
caller’s own limits, here and on every other response a limit applies
to. A request refused with rate-limited uses no quota. One
refused after that check, for its scope, role, subscription, or kind of
client, still counts, so once a quota is used up such a request gets
429 instead of its 403. A request that fails authentication is
not counted. An ask that the organization’s
AI spending budget can’t cover returns ai-budget-exceeded instead,
with Retry-After at the end of the budget’s window: that budget
counts what asks cost, not how many there are. An ask that the
organization’s premium units for the day can’t cover returns
premium-quota-exceeded, with limit (org-premium-day), resetsAt
(the next midnight UTC), and Retry-After. That is the plan’s
allowance: a plan with no premium units never covers an ask, and a
higher plan may. A refused ask uses no units.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Examples
An ask the premium units can't cover
{ "limit": "org-premium-day", "resetsAt": "2026-11-08T00:00:00Z", "status": 429, "title": "Too Many Requests", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "type": "https://fedwright.com/problems/premium-quota-exceeded"}A quota used up
{ "limit": "org-day", "resetsAt": "2026-11-08T00:00:00Z", "status": 429, "title": "Too Many Requests", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736", "type": "https://fedwright.com/problems/rate-limited"}Headers
Section titled “Headers”For each limit in RateLimit-Policy, the requests r its window still
allows and the seconds t until the window resets, such as
"org-burst";r=7;t=40, "org-day";r=62;t=41000.
The caller’s rate limits, in the IETF HTTPAPI RateLimit header fields:
each limit’s name, its quota q, and its window w in seconds, such as
"org-burst";q=20;w=60, "org-day";q=100;w=86400.
Seconds to wait before retrying.
On a 429 with an empty body (and on the successful responses that carry
these headers), the exhausted rule’s limit and window w in seconds,
such as 3000, 3000;w=2592000. The window names the quota: 60 is burst,
86400 is daily, and 2592000 is monthly.
What is left in that rule’s window (0 on a 429).
Seconds until that rule’s window resets.
default
Section titled “default”Any other error. A request body over 64 KiB returns 413
(payload-too-large), and a request that takes longer than 10 seconds
(90 for askOpportunities) returns 503 (request-timeout). An invitation when the API can’t send mail returns 503
(mail-unavailable), and creates nothing. An unexpected failure returns 500 (internal-error)
with only type, title, status, and traceId.
RFC 9457 Problem Details.
object
An explanation specific to this occurrence of the problem. It is absent for server errors.
Validation errors, by field path.
object
A URI reference that identifies this occurrence of the problem, when the API provides one.
On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.
On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.
The HTTP status code of the response, from 400 to 599.
A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.
W3C trace ID of the failed request.
https://fedwright.com/problems/{code}, the same in every environment.
Example generated
{ "detail": "example", "errors": { "additionalProperty": [ "example" ] }, "instance": "example", "limit": "example", "resetsAt": "2026-04-15T12:00:00Z", "status": 1, "title": "example", "traceId": "example", "type": "https://example.com"}