> ## Documentation Index > Fetch the complete documentation index at: https://docs.govly.com/llms.txt > Use this file to discover all available pages before exploring further. # Search opportunities > Search opportunities with the constrained public parameter set shared by MCP search_opportunities. Defaults to open opportunities and excludes prediction records from search results. Searches all dates unless a date bound is supplied, orders by newest modified date unless sort is supplied, and returns stored opportunity dates. Repeat the same filters with each cursor. Unresolved buyers or unsupported type filters fail with 400 rather than returning a broader search. ## OpenAPI ````yaml /openapi/tools-v1.yaml post /api/tools/v1/opportunities/search openapi: 3.1.0 info: title: Govly Tools API version: 1.0.0-alpha description: > ALPHA / UNSTABLE: This API is still in active development. Endpoint behavior, request fields, response fields, error codes, and operation names may change before the Tools API is declared stable. REST-callable tool surface for agent and automation workflows. Agents are the primary consumer, but integrations can be built on this API. Responses are JSON for typed clients; MCP tools may render action results into text-oriented formats separately. Validating requests: validate against this schema in your client before sending. Govly ignores a request field it does not recognize rather than rejecting it, so a misspelled filter name is not applied — the response returns 200 with a broader result set than you intended, and nothing marks the difference. Where a request body declares `additionalProperties: false`, strict client-side validation is what catches that. Fields sent with the wrong type are rejected with 400 on most endpoints; validate types in your client too rather than relying on it. Rate limits: each resource (for example awards, opportunities, or workspaces) allows 70 requests per minute per user. Exceeding it returns 429 with the standard error envelope, `code: rate_limited`, and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also subject to the Enterprise API limit of 300 requests per minute per key; see the Rate Limits page. servers: - url: https://app.govly.com security: - bearerApiKey: [] - headerApiKey: [] tags: - name: Opportunities description: Search, fetch, and inspect Govly opportunity records. - name: Awards description: Search and inspect awarded government contracts. - name: Contacts description: Search and inspect government points of contact. - name: Signals description: Search clustered procurement and market intelligence signals. - name: Places description: Resolve place names to canonical Govly Place ids. - name: Product Catalogs description: List government contract price lists and search their line items. - name: Workspaces description: Create, update, and inspect opportunity workspaces. - name: Workspace Members description: Add users and teams to workspaces. - name: Workspace Attachments description: List and upload workspace attachments. - name: Workspace Comments description: Post comments to workspaces. - name: Follows description: Follow opportunities and related workspace activity. - name: Shares description: Share opportunities, awards, and contacts with colleagues by email. - name: Saved Searches description: List saved opportunity searches and cached matches. - name: Documents description: >- Read document representations and request temporary original-file downloads. - name: Quote Submissions description: >- Inspect quote submission requirements, submit quotes, and poll submission status. - name: Inbox description: Read and triage the authenticated user's matched inbox items. paths: /api/tools/v1/opportunities/search: post: tags: - Opportunities summary: Search opportunities description: > Search opportunities with the constrained public parameter set shared by MCP search_opportunities. Defaults to open opportunities and excludes prediction records from search results. Searches all dates unless a date bound is supplied, orders by newest modified date unless sort is supplied, and returns stored opportunity dates. Repeat the same filters with each cursor. Unresolved buyers or unsupported type filters fail with 400 rather than returning a broader search. operationId: search_opportunities requestBody: required: false content: application/json: schema: type: object additionalProperties: false properties: query: type: string cursor: type: string description: >- Opaque cursor from the previous response's meta.nextCursor. Omit for the first page. perPage: type: integer default: 25 maximum: 100 status: default: open description: > Defaults to open for actionable opportunities. Use all, expired, cancelled, awarded, or not_cancelled for historical or specific lookup requests. Pass an array to match several statuses at once. Prediction records are always excluded. oneOf: - type: string enum: - open - all - expired - cancelled - awarded - not_cancelled - type: array items: type: string enum: - open - all - expired - cancelled - awarded - not_cancelled naics: type: array items: type: string description: NAICS codes to filter by, such as 541519. placeIds: type: array items: type: string description: > Canonical Govly Place ids to filter by, from the place search or list tools. Matches at any administrative level, so a state id also matches opportunities tagged only to a city inside it. placeIdsNone: type: array items: type: string description: >- Canonical Govly Place ids to exclude. Same matching rules as placeIds. buyerDescription: type: string description: >- Federal buyer in natural language. An unrecognized buyer returns 400; use a more specific name. Not supported for sled or international searches. includeSubBuyers: type: boolean description: >- Include child agencies when true; use only with buyerDescription. If omitted, buyer selection determines whether children are included. Explicit false searches the selected buyer only. recordType: type: array items: type: string enum: - Solicitation - Event - Other description: >- Restrict published record types. Empty or omitted means all published types. Unsupported values are rejected. noticeType: type: array items: type: string enum: - Amendment - Award - Catalog Request - Combined Synopsis - Market Research Request - Presolicitation - Q&A - Reminder - Request for Information - Request for Proposal - Request for Quote - Reverse Auction - Sources Sought - Event - Industry Day - Presolicitation Conference - Site Visit - Justification - Other description: >- Restrict notice types. Empty or omitted adds no restriction. Unsupported values are rejected. searchType: type: string enum: - fed - sled - international description: > Market type: fed for federal, sled for state/local/education, international for non-US. Defaults to the authenticated user's market focus (fed or sled). sled and international require the matching organization subscription. postedAfter: type: string description: >- Only include opportunities posted at or after this date/time. ISO 8601 dates work best. postedBefore: type: string description: >- Only include opportunities posted at or before this date/time. ISO 8601 dates work best. modifiedAfter: type: string description: >- Only include opportunities modified at or after this date/time. ISO 8601 dates work best. modifiedBefore: type: string description: >- Only include opportunities modified at or before this date/time. ISO 8601 dates work best. respondByAfter: type: string description: >- Only include opportunities with a response deadline at or after this date/time. ISO 8601 dates work best. respondByBefore: type: string description: >- Only include opportunities with a response deadline at or before this date/time. ISO 8601 dates work best. awardedAfter: type: string description: >- Only include awarded opportunities awarded at or after this date/time. ISO 8601 dates work best. awardedBefore: type: string description: >- Only include awarded opportunities awarded at or before this date/time. ISO 8601 dates work best. sort: type: string enum: - modified_at - posted_at - respond_by - relevance sortDirection: type: string enum: - asc - desc responses: '200': description: Matching opportunities content: application/json: schema: type: object required: - data - meta properties: data: type: array items: $ref: '#/components/schemas/OpportunitySearchResult' meta: $ref: '#/components/schemas/OpportunitySearchMeta' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/RateLimited' components: schemas: OpportunitySearchResult: type: object required: - id description: >- Search fields only. Dates are stored opportunity values; attachment/source detail is available through show_opportunity. properties: id: type: string description: >- Govly opportunity ID. Use this ID for show requests, workspace associations, and links. title: type: string displayName: type: string description: >- Human-readable opportunity reference, usually source name plus identifier. identifier: type: string description: >- Public opportunity identifier, such as a solicitation or request number. This may differ from raw source-system IDs when Govly merges related notices. externalUrl: type: string format: uri links: type: object description: Canonical links for this opportunity. Prefer these over externalUrl. required: - self properties: self: type: string format: uri description: Canonical Govly app link for this opportunity. external: type: string format: uri description: >- Source-system link, omitted when the source does not provide one. recordType: type: string status: type: string enum: - open - expired - cancelled - awarded - forecasted - unknown postedAt: type: string format: date-time modifiedAt: type: string format: date-time respondBy: type: string format: date-time cancelledAt: type: string format: date-time awardedAt: type: string format: date-time aiTitle: type: string aiSummary: type: string buyer: type: object description: Search and detail. Government buyer and its hierarchy. properties: id: type: string name: type: string domains: type: array items: type: string hierarchy: type: array items: type: string locations: type: array description: Search and detail. Displayable opportunity locations. items: $ref: '#/components/schemas/OpportunityLocation' naics: type: array description: Search and detail. Most-specific NAICS codes. items: type: string psc: type: array description: Search and detail. Most-specific Product and Service Codes. items: type: string nigp: type: array description: Search and detail. Most-specific NIGP codes. items: type: string unspsc: type: array description: Search and detail. Most-specific UNSPSC codes. items: type: string jurisdiction: type: object properties: id: type: string name: type: string isoCode: type: string contractVehicle: type: object properties: id: type: string name: type: string tags: type: object description: >- Tags grouped by context. Keys are contexts — "contract" holds contract vehicle groups such as SEWP V groups (and non-vehicle markers such as "Manual" for hand-created opportunities), "warning" holds pursuit cautions such as clearance designations, "productCategory" holds product classifications. Each value is a list of objects with a stable "slug" and a display "label". An empty object when the opportunity has no tags — the key is always present. additionalProperties: type: array items: type: object required: - slug - label properties: slug: type: string label: type: string followerCount: type: integer description: >- Count of active follow rows across visible workspaces for this opportunity. followedByCurrentUser: type: boolean description: >- Whether the authenticated user actively follows any visible workspace for this opportunity. followedByCurrentOrganization: type: boolean description: >- Whether the authenticated user's organization actively follows any visible workspace for this opportunity. workspaces: type: array description: >- Visible workspaces associated with this opportunity, including active follow context. items: $ref: '#/components/schemas/OpportunityWorkspace' OpportunitySearchMeta: type: object required: - total - returnedCount - totalIsLowerBound - perPage - searchType - nextCursor properties: total: type: integer description: >- Indexed matches, which can exceed visible materialized records. A lower bound when totalIsLowerBound is true. returnedCount: type: integer description: Number of records actually returned on this page. totalIsLowerBound: type: boolean description: >- Whether the index stopped counting before establishing an exact total. perPage: type: integer searchType: type: string enum: - fed - sled - international nextCursor: type: - string - 'null' description: >- Continue with the same filters while present, even when returnedCount is zero. Buyer selection is reused on subsequent pages. OpportunityLocation: type: object properties: placeLocationId: type: string postalCode: type: string city: type: string region: type: string street: type: string place: type: string country: type: string countryCode: type: string label: type: string type: type: string OpportunityWorkspace: type: object required: - id - name - status - followerCount - follows properties: id: type: string name: type: string organizationDefault: type: boolean organization: type: object properties: id: type: string name: type: string status: type: object required: - category - label properties: category: type: string label: type: string followerCount: type: integer description: Count of active follow rows on this workspace. followedByCurrentUser: type: boolean followedByCurrentOrganization: type: boolean follows: type: array description: >- Active workspace follows. Inactive/unfollowed/disinterested rows are omitted. items: $ref: '#/components/schemas/WorkspaceMember' ErrorEnvelope: type: object required: - errors properties: errors: type: array items: type: object required: - status - code - title - detail properties: status: type: string code: type: string title: type: string detail: type: string source: type: object properties: pointer: type: string RateLimitError: type: object required: - error properties: error: type: string WorkspaceMember: type: object required: - id - member properties: id: type: string state: type: string notifications: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time member: type: object required: - type - id properties: type: type: string enum: - user - team id: type: string name: type: string email: type: string format: email organization: type: object properties: id: type: string name: type: string responses: Error: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: > Too many requests. Two limiters can produce this status and they use different bodies. The per-user limit of 70 requests per minute for each resource returns the standard error envelope with `code: rate_limited` and a `Retry-After` header. Keys sent in the `X-API-KEY` header are also subject to the Enterprise API limit of 300 requests per minute per key, which returns the plain `error` form with `Retry-After` and the `X-RateLimit-*` headers. Clients should accept either body. headers: Retry-After: description: Seconds to wait before retrying. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/ErrorEnvelope' - $ref: '#/components/schemas/RateLimitError' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key headerApiKey: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.