> ## 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.

# Show an opportunity



## OpenAPI

````yaml /openapi/tools-v1.yaml get /api/tools/v1/opportunities/{id}
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/{id}:
    get:
      tags:
        - Opportunities
      summary: Show an opportunity
      operationId: show_opportunity
      parameters:
        - $ref: '#/components/parameters/id'
      responses:
        '200':
          description: Opportunity
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Opportunity'
                  meta:
                    $ref: '#/components/schemas/ActionMeta'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '404':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    id:
      name: id
      in: path
      required: true
      schema:
        type: string
  schemas:
    Opportunity:
      type: object
      required:
        - id
      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
        aiPeriodOfPerformance:
          type: string
          description: Detail only. AI-generated period-of-performance summary.
        estimatedContractValue:
          type: object
          description: >-
            Detail only. Normalized estimated contract value in USD from
            authorized explicit sources, falling back to the opportunity AI
            estimate.
          properties:
            min:
              type: number
              format: double
            max:
              type: number
              format: double
        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'
        aggregateAttachments:
          type: array
          items:
            $ref: '#/components/schemas/OpportunityAttachment'
        opportunitySources:
          type: array
          items:
            $ref: '#/components/schemas/OpportunitySource'
        contacts:
          type: array
          description: >-
            Detail only. Up to 100 government contacts linked to the opportunity
            or its attachments, ordered by id. email and phoneNumbers appear
            only for paid seats and only when the opportunity's source data is
            not anonymized for the caller's organization.
          items:
            $ref: '#/components/schemas/OpportunityContact'
    ActionMeta:
      type: object
      properties:
        availableActions:
          type: array
          description: >-
            Structured hints for useful follow-up actions. These are advisory;
            clients should still rely on tool schemas and authorization.
          items:
            $ref: '#/components/schemas/AvailableAction'
        sourceCoverage:
          type: object
          description: >-
            Result-local source inventory and guidance for claims that require
            opportunity attachment content.
          required:
            - opportunityAttachmentCount
            - guidance
          properties:
            opportunityAttachmentCount:
              type: integer
              minimum: 0
            guidance:
              type: string
    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'
    OpportunityAttachment:
      type: object
      required:
        - id
        - documentType
        - filename
        - redacted
        - contentAvailable
      properties:
        id:
          type: string
          description: >-
            Canonical OppAttachment.id. Pass this value to document_read and
            document_download.
        documentType:
          type: string
          const: opportunity_attachment
        filename:
          type: string
        contentType:
          type: string
        byteSize:
          type: integer
        contentAvailable:
          type: boolean
          description: Whether attachment content is available to the current organization.
        redacted:
          type: boolean
          deprecated: true
          description: >-
            Deprecated inverse of contentAvailable. Retained for Tools API v1
            compatibility.
        tags:
          type: array
          items:
            type: string
        file:
          $ref: '#/components/schemas/AttachmentFile'
    OpportunitySource:
      type: object
      required:
        - id
        - attachments
      properties:
        id:
          type: string
        postedAt:
          type: string
          format: date-time
        externalUrl:
          type: string
          format: uri
        noticeType:
          type: string
        recordType:
          type: string
        cancelReason:
          type: string
          description: >-
            Original cancellation reason, with source-specific sharing
            redaction.
        reportedChanges:
          type: array
          description: >-
            Source-reported amendments; dates are omitted when the source did
            not supply them.
          items:
            type: object
            properties:
              amendmentId:
                type: string
              versionNumber:
                type: integer
              modifiedAt:
                type: string
                description: >-
                  ISO 8601 timestamp or YYYY-MM-DD when only a calendar date is
                  known.
              text:
                type: string
                description: >-
                  Original change reason, with source-specific sharing
                  redaction.
              documents:
                type: array
                items:
                  type: object
                  required:
                    - filename
                    - status
                  properties:
                    filename:
                      type: string
                    status:
                      type: string
                      enum:
                        - matched
                        - not_captured
                        - ambiguous
                    attachment:
                      $ref: '#/components/schemas/OpportunityAttachment'
                      description: >-
                        Present for one unambiguous visible revision; ordinary
                        attachment access and URL controls apply.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/OpportunityAttachment'
    OpportunityContact:
      type: object
      required:
        - id
      description: >-
        A contact embedded in show_opportunity, including identity, titles,
        active status, and permitted email and phone numbers. When active is
        true, use show_contact for buyers, vendors, and places.
      properties:
        id:
          type: string
        name:
          type: string
        titles:
          type: array
          items:
            type: string
        active:
          type: boolean
        email:
          type: string
          description: >-
            Present only for paid callers when the opportunity is not anonymized
            for their organization.
        phoneNumbers:
          type: array
          items:
            type: string
          description: >-
            Present only for paid callers when the opportunity is not anonymized
            for their organization.
    AvailableAction:
      type: object
      required:
        - name
        - description
        - arguments
        - idPaths
      properties:
        name:
          type: string
          description: MCP/tool operation name.
        description:
          type: string
        arguments:
          type: object
          description: Static arguments to pass to the action.
        idPaths:
          type: array
          description: >-
            JSON paths where IDs for this action can be found in the current
            response.
          items:
            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
    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
    AttachmentFile:
      type: object
      description: >-
        Presigned download metadata. Omitted when attachment content is
        unavailable or URLs are excluded.
      required:
        - url
        - expiresAt
      properties:
        url:
          type: string
          format: uri
        expiresAt:
          type: string
          format: date-time
  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.