find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/govly:govly-inbox-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Govly Tools API (Alpha) Inbox 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.'
servers:
- url: https://app.govly.com
security:
- bearerApiKey: []
- headerApiKey: []
tags:
- name: Inbox
  description: Read and triage the authenticated user's matched inbox items.
paths:
  /api/tools/v1/inbox_items:
    get:
      tags:
      - Inbox
      operationId: list_inbox_items
      summary: List inbox items
      description: List the authenticated user's active inbox items (Govly AI matches and saved-search matches), newest first.
      parameters:
      - $ref: '#/components/parameters/cursor'
      - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Inbox items
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InboxItem'
                  meta:
                    $ref: '#/components/schemas/CursorMeta'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
  /api/tools/v1/inbox_items/search:
    post:
      tags:
      - Inbox
      operationId: search_inbox_items
      summary: Search inbox items
      description: Full-text search and filter the authenticated user's inbox items. Returns matchable-type aggregation counts.
      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'
  /api/tools/v1/inbox_items/{id}:
    get:
      tags:
      - Inbox
      operationId: show_inbox_item
      summary: Show an inbox item
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Inbox item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxItemEnvelope'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /api/tools/v1/inbox_items/{id}/accept:
    post:
      tags:
      - Inbox
      operationId: accept_inbox_item
      summary: Accept (follow) an inbox item
      description: Follow the underlying opportunity, award, or signal and create or reuse its default workspace. Accept is FINAL and cannot be reversed with restore. The response meta includes the resulting workspaceId.
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Accepted inbox item
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/InboxItem'
                  meta:
                    $ref: '#/components/schemas/InboxAcceptMeta'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /api/tools/v1/inbox_items/{id}/dismiss:
    post:
      tags:
      - Inbox
      operationId: dismiss_inbox_item
      summary: Dismiss an inbox item
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Dismissed inbox item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxItemEnvelope'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
  /api/tools/v1/inbox_items/{id}/decline:
    post:
      tags:
      - Inbox
      operationId: decline_inbox_item
      summary: Decline (reject) an inbox item as a bad fit
      description: Mark the item a bad fit, optionally with a reason that feeds the organization's matching-exclusions memory. Reversible with restore.
      parameters:
      - $ref: '#/components/parameters/id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                reason:
                  type: string
                  enum:
                  - bad_fit
                  - irrelevant
                  - cannot_bid
                  - bad_timing
                  - other
      responses:
        '200':
          description: Declined inbox item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxItemEnvelope'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
  /api/tools/v1/inbox_items/{id}/restore:
    post:
      tags:
      - Inbox
      operationId: restore_inbox_item
      summary: Restore a dismissed or declined inbox item
      description: Return a dismissed or bad-fit item to the active inbox. Only dismissed or bad-fit items can be restored — an accepted item cannot.
      parameters:
      - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Restored inbox item
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboxItemEnvelope'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
components:
  schemas:
    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
    InboxItemEnvelope:
      type: object
      required:
      - data
      properties:
        data:
          $ref: '#/components/schemas/InboxItem'
    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'
    InboxAcceptMeta:
      type: object
      required:
      - state
      - feedback
      - matchableType
      - matchableId
      - final
      properties:
        state:
          type: string
        feedback:
          type: string
        matchableType:
          type: string
        matchableId:
          type: string
        workspaceId:
          type:
          - string
          - 'null'
          description: Default workspace the accept followed, when one exists.
        final:
          type: boolean
          description: Always true — accept is irreversible.
    InboxAggregations:
      type: object
      required:
      - matchableType
      properties:
        matchableType:
          type: object
          description: Count of matching items per matchable type.
          additionalProperties:
            type: integer
    CursorMeta:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          description: Number of records in this page.
        totalCount:
          type: integer
          description: 'Total matching records (award search only), capped at 10,000 by the search engine. Pagination via nextCursor is not limited by this cap.

            '
        perPage:
          type: integer
        nextCursor:
          type:
          - string
          - 'null'
    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'
    InboxItemOrigin:
      type: object
      required:
      - sourceType
      properties:
        sourceType:
          type: string
          enum:
          - govly_ai
          - saved_search
        savedSearchId:
          type: string
        savedSearchName:
          type: string
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  parameters:
    perPage:
      name: perPage
      in: query
      required: false
      schema:
        type: integer
        default: 25
        maximum: 100
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
    cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
  securitySchemes:
    bearerApiKey:
      type: http
      scheme: bearer
      bearerFormat: API key
    headerApiKey:
      type: apiKey
      in: header
      name: X-API-KEY