> ## 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 inbox items > Full-text search and filter the authenticated user's inbox items. Returns matchable-type aggregation counts. ## OpenAPI ````yaml /openapi/tools-v1.yaml post /api/tools/v1/inbox_items/search openapi: 3.1.0 info: title: Govly Tools API (Alpha) 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. 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: 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: 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/inbox_items/search: post: tags: - Inbox summary: Search inbox items description: > Full-text search and filter the authenticated user's inbox items. Returns matchable-type aggregation counts. operationId: search_inbox_items 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 sort: type: string enum: - ranked_score - created_at - deadline_at sortDirection: type: string enum: - asc - desc state: type: array items: type: string enum: - unread - seen - actioned - dismissed matchableType: type: array items: type: string enum: - Opp - Award - ProcurementSignal::Cluster recordType: type: array items: type: string sourceType: type: string enum: - govly_ai - saved_search naicsCodes: type: array items: type: string createdAfter: type: string createdBefore: type: string deadlineAtFrom: type: string deadlineAtTo: type: string responses: '200': description: Matching inbox items content: application/json: schema: type: object required: - data - meta - aggregations properties: data: type: array items: $ref: '#/components/schemas/InboxItem' meta: $ref: '#/components/schemas/InboxSearchMeta' aggregations: $ref: '#/components/schemas/InboxAggregations' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' components: schemas: InboxItem: type: object required: - id - matchableId - matchableType - state - origins properties: id: type: string matchableId: type: string matchableType: type: string enum: - Opp - Award - ProcurementSignal::Cluster state: type: string enum: - unread - seen - actioned - dismissed feedback: type: string enum: - followed - dismissed - bad_fit feedbackReason: type: string enum: - bad_fit - irrelevant - cannot_bid - bad_timing - other title: type: string description: type: string fitReason: type: string fitScore: type: number sourceType: type: string enum: - govly_ai - saved_search description: How the item first reached the inbox. identifier: type: string recordType: type: string deadlineAt: type: string format: date-time postedOrAwardedDate: type: string format: date publicEntityNames: type: array items: type: string isoCode: type: string naicsCodes: type: array items: type: string createdAt: type: string format: date-time highlight: type: object description: Per-field search highlights. Only present on search results. additionalProperties: type: string origins: type: array description: Every source that surfaced this (deduped) item. items: $ref: '#/components/schemas/InboxItemOrigin' InboxSearchMeta: type: object required: - total - nextCursor properties: total: type: integer description: Total matching items (capped at 10000 by the search index). nextCursor: type: - string - 'null' InboxAggregations: type: object required: - matchableType properties: matchableType: type: object description: Count of matching items per matchable type. additionalProperties: type: integer InboxItemOrigin: type: object required: - sourceType properties: sourceType: type: string enum: - govly_ai - saved_search savedSearchId: type: string savedSearchName: type: string 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 responses: Error: description: Error response content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key headerApiKey: type: apiKey in: header name: X-API-KEY ````