openapi: 3.1.0
info:
  title: GUILD Public Opportunity Feed API
  version: "1.0.0"
  summary: Curated public opportunity feed for approved partner backends.
  description: >
    Backend-only API for approved media and channel partners to retrieve up to
    five GUILD-curated public and outsourced manufacturing opportunities.
servers:
  - url: https://app.guildai.co
    description: Production
security:
  - bearerAuth: []
paths:
  /api/integrations/opportunity-feed:
    get:
      operationId: getPublicOpportunityFeed
      summary: Get curated public opportunity picks.
      description: >
        Returns a narrow public DTO for the authenticated integration client.
        Tokens must be used only from partner backend infrastructure.
      tags:
        - Opportunity Feed
      responses:
        "200":
          description: Curated feed returned.
          headers:
            Cache-Control:
              description: Server cache directive for the feed response. Respect no-store when present.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OpportunityFeedResponse"
              examples:
                success:
                  summary: One curated opportunity
                  value:
                    ok: true
                    client:
                      id: 11111111-1111-4111-8111-111111111111
                      slug: partner-news-client
                    opportunities:
                      - rank: 1
                        weekStart: "2026-06-22"
                        solicitationNumber: SPE4A6-26-T-0000
                        nsn: 5310-00-000-0000
                        itemName: Precision fastener assembly
                        description: Curated public manufacturing opportunity with defense supply relevance.
                        quantity: 1250
                        estimatedSupplierManufacturingValue: 87500
                        leadTime: 90 days
                        sampleImageUrl: https://app.guildai.co/public/opportunity-images/sample-fastener.jpg
                        sampleImageAlt: Precision fastener assembly
                        requiredCertifications:
                          - ISO 9001
                          - ITAR readiness
                        engagementUrl: https://apply.guildai.co
        "401":
          description: Missing, malformed, expired, disabled, or invalid Bearer token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              examples:
                unauthorized:
                  value:
                    error: Unauthorized
        "405":
          description: Method not allowed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Request volume exceeded the agreed integration pattern.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Feed unavailable or a required curated field failed validation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Backend-only GUILD-issued integration token.
  schemas:
    OpportunityFeedResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - client
        - opportunities
      properties:
        ok:
          type: boolean
          const: true
        client:
          type: object
          additionalProperties: false
          required:
            - id
            - slug
          properties:
            id:
              type: string
              description: Integration client UUID.
            slug:
              type: string
              description: Public integration client slug.
              examples:
                - partner-news-client
        opportunities:
          type: array
          maxItems: 5
          items:
            $ref: "#/components/schemas/Opportunity"
    Opportunity:
      type: object
      additionalProperties: false
      required:
        - rank
        - weekStart
        - solicitationNumber
        - itemName
        - description
        - quantity
        - estimatedSupplierManufacturingValue
        - leadTime
        - sampleImageUrl
        - requiredCertifications
        - engagementUrl
      properties:
        rank:
          type: integer
          minimum: 1
          maximum: 5
        weekStart:
          type: string
          format: date
        solicitationNumber:
          type: string
          minLength: 1
        nsn:
          type:
            - string
            - "null"
          description: National Stock Number when available.
        itemName:
          type: string
          minLength: 1
        description:
          type: string
          minLength: 1
        quantity:
          type: number
          minimum: 1
        estimatedSupplierManufacturingValue:
          type: number
          minimum: 0
          description: Estimated supplier or manufacturing value in USD.
        leadTime:
          type: string
          minLength: 1
        sampleImageUrl:
          type: string
          format: uri
          description: Public GUILD-controlled product image URL.
        sampleImageAlt:
          type:
            - string
            - "null"
        requiredCertifications:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
        engagementUrl:
          type: string
          format: uri
          description: Public intake URL for manufacturer engagement.
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          description: Redacted public error message.
          examples:
            - Unauthorized
            - Method not allowed
            - Request failed