openapi: 3.1.0
info:
  title: Gov Contract Scout
  version: 1.0.0
  summary: x402-native SAM.gov opportunity intelligence for agentic capture workflows.
  description: >
    Gov Contract Scout searches normalized SAM.gov Contract Opportunities data
    and returns opportunity briefs, business-profile matches, subcontractor
    work packages, bid/no-bid checks, watchlists, and digests for agents.
    It preserves native x402 payment and does not use marketplace billing
    wrappers.
  contact:
    name: Daniel Hallman
servers:
  - url: https://agentic-gov-contracts.vercel.app
    description: Production
paths:
  /:
    get:
      operationId: getProductPage
      summary: Product page
      responses:
        "200":
          description: HTML product page.
          content:
            text/html:
              schema:
                type: string
  /health:
    get:
      operationId: getHealth
      summary: Health and database status
      responses:
        "200":
          description: Health status.
          content:
            application/json:
              schema:
                type: object
  /api/opportunities/search:
    get:
      operationId: searchOpportunities
      summary: Search SAM.gov opportunities
      description: Paid x402 endpoint for full-text and structured opportunity search.
      parameters:
        - name: q
          in: query
          schema:
            type: string
          description: Full-text query.
        - name: agency
          in: query
          schema:
            type: string
        - name: naics
          in: query
          schema:
            type: string
        - name: psc
          in: query
          schema:
            type: string
        - name: setAside
          in: query
          schema:
            type: string
        - name: location
          in: query
          schema:
            type: string
        - name: noticeType
          in: query
          schema:
            type: string
        - name: active
          in: query
          schema:
            type: boolean
        - name: dueBefore
          in: query
          schema:
            type: string
            format: date
        - name: dueAfter
          in: query
          schema:
            type: string
            format: date
        - name: postedAfter
          in: query
          schema:
            type: string
            format: date
        - name: postedBefore
          in: query
          schema:
            type: string
            format: date
        - name: complexity
          in: query
          schema:
            type: string
            enum: [low, medium, high]
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: Search results.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/{noticeId}:
    get:
      operationId: getOpportunity
      summary: Get one opportunity
      description: Paid x402 endpoint returning normalized fields and an opportunity brief.
      parameters:
        - name: noticeId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Opportunity detail.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/brief:
    post:
      operationId: createOpportunityBrief
      summary: Create opportunity brief
      description: Paid x402 endpoint for rule checks, requirement signals, subcontractor preview, and capture next actions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoticeAnalysisRequest"
      responses:
        "200":
          description: Opportunity brief.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/match:
    post:
      operationId: matchOpportunities
      summary: Match a profile against opportunities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                profile:
                  $ref: "#/components/schemas/BusinessProfile"
                limit:
                  type: integer
      responses:
        "200":
          description: Ranked opportunity matches.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/subcontractor-plan:
    post:
      operationId: createSubcontractorPlan
      summary: Create subcontractor plan
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoticeAnalysisRequest"
      responses:
        "200":
          description: Work packages, search queries, outreach drafts, margin model, and compliance warnings.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/bid-no-bid:
    post:
      operationId: createBidNoBid
      summary: Create bid/no-bid decision
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NoticeAnalysisRequest"
      responses:
        "200":
          description: Recommendation, score, margin model, risk signals, rule checks, and required next actions.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/watch:
    post:
      operationId: createOpportunityWatch
      summary: Create a watch filter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                filters:
                  type: object
      responses:
        "200":
          description: Watch metadata and digest call body.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /api/opportunities/digest:
    post:
      operationId: createOpportunityDigest
      summary: Create opportunity digest
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                watchId:
                  type: string
                filters:
                  type: object
                since:
                  type: string
                  format: date
                limit:
                  type: integer
      responses:
        "200":
          description: Digest of matching opportunities.
          content:
            application/json:
              schema:
                type: object
        "402":
          $ref: "#/components/responses/PaymentRequired"
      security:
        - x402Payment: []
  /mcp:
    post:
      operationId: postMcpJsonRpc
      summary: MCP JSON-RPC endpoint
      description: Supports initialize, tools/list, and tools/call. Tool calls return paid x402 endpoint instructions.
      responses:
        "200":
          description: JSON-RPC response.
components:
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: x402 payment payload after reading PAYMENT-REQUIRED.
  responses:
    PaymentRequired:
      description: x402 payment required.
      headers:
        PAYMENT-REQUIRED:
          description: Base64-encoded x402 payment challenge.
          schema:
            type: string
      content:
        application/json:
          schema:
            type: object
  schemas:
    SearchResponse:
      type: object
      properties:
        query:
          type: object
        database:
          type: object
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        opportunities:
          type: array
          items:
            $ref: "#/components/schemas/OpportunitySummary"
    OpportunitySummary:
      type: object
      properties:
        noticeId:
          type: string
        solicitationNumber:
          type: string
        title:
          type: string
        agency:
          type: string
        noticeType:
          type: string
        active:
          type: boolean
        postedDate:
          type: string
          format: date
        responseDeadline:
          type: string
          format: date
        naicsCode:
          type: string
        classificationCode:
          type: string
        setAside:
          type: string
        setAsideCode:
          type: string
        complexity:
          type: object
        links:
          type: object
    NoticeAnalysisRequest:
      type: object
      required:
        - noticeId
      properties:
        noticeId:
          type: string
        estimatedContractValue:
          type: number
        estimatedSubcontractorCost:
          type: number
        targetMarginPercent:
          type: number
        profile:
          $ref: "#/components/schemas/BusinessProfile"
    BusinessProfile:
      type: object
      properties:
        keywords:
          type: array
          items:
            type: string
        capabilities:
          type: array
          items:
            type: string
        naicsCodes:
          type: array
          items:
            type: string
        pscCodes:
          type: array
          items:
            type: string
        setAsideStatuses:
          type: array
          items:
            type: string
        states:
          type: array
          items:
            type: string
        riskTolerance:
          type: string
          enum: [low, medium, high]
