openapi: 3.1.0
info:
  title: Barbine Worldwide Assessment Scheduler
  version: 1.6.0
  description: Public API and discovery surface for the Barbine Worldwide assessment builder and scheduling portal.
servers:
  - url: https://assessments.platphormnews.com
paths:
  /api/health:
    get:
      summary: Service health
      responses:
        "200":
          description: Health payload
  /api/v1/health:
    get:
      summary: Versioned service health
      responses:
        "200":
          description: Health payload
  /api/docs:
    get:
      summary: Human-readable API documentation
      responses:
        "200":
          description: HTML documentation
  /api/mcp:
    get:
      summary: MCP endpoint metadata
      responses:
        "200":
          description: MCP metadata
    post:
      summary: MCP JSON-RPC endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                - type: array
      responses:
        "200":
          description: JSON-RPC response
  /api/v1/platphorm/registration:
    get:
      summary: PlatPhormNews registration payload
      responses:
        "200":
          description: Public self-describing registration payload for root graph ingestion
  /api/v1/operator/leads:
    get:
      summary: Protected operator lead queue
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      responses:
        "200":
          description: Protected lead queue
        "401":
          description: PLATPHORM_API_KEY required
        "503":
          description: Storage or protected auth is not configured
  /portal/{token}/summary.md:
    get:
      summary: Token-scoped customer assessment summary
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Markdown assessment scope summary for the portal owner
  /portal/{token}/report.md:
    get:
      summary: Token-scoped delivered assessment report
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Markdown final report for the portal owner after protected delivery
        "404":
          description: Report has not been delivered or token is unknown
  /api/v1/portal/{token}/report:
    post:
      summary: Protected operator report delivery
      security:
        - PlatPhormApiKey: []
        - PlatPhormBearer: []
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - executiveSummary
                - findings
                - recommendations
                - nextSteps
              properties:
                title:
                  type: string
                executiveSummary:
                  type: string
                findings:
                  type: array
                  items:
                    type: string
                recommendations:
                  type: array
                  items:
                    type: string
                nextSteps:
                  type: array
                  items:
                    type: string
      responses:
        "200":
          description: Report delivered
        "401":
          description: PLATPHORM_API_KEY required
        "503":
          description: Protected delivery or storage is not configured
  /operator:
    get:
      summary: Operator cockpit shell
      responses:
        "200":
          description: Public-safe operator UI shell; protected data loads require PLATPHORM_API_KEY
  /share:
    get:
      summary: Public share URL
      responses:
        "200":
          description: Share page with temporary confirmation URL and copy/share controls
  /.well-known/platphorm.json:
    get:
      summary: Well-known PlatPhormNews registration payload
      responses:
        "200":
          description: Public self-describing registration payload
  /.well-known/ai-plugin.json:
    get:
      summary: Legacy AI plugin applicability
      responses:
        "200":
          description: Honest non-applicable legacy AI plugin manifest with links to supported discovery surfaces
  /opengraph-image:
    get:
      summary: Open Graph image
      responses:
        "200":
          description: Generated PNG social image
  /llms.txt:
    get:
      summary: Concise AI-readable site summary
      responses:
        "200":
          description: Plain text summary
  /llms-full.txt:
    get:
      summary: Complete AI-readable capability summary
      responses:
        "200":
          description: Plain text capability document
  /llms-index.json:
    get:
      summary: JSON index of AI-readable files and public capabilities
      responses:
        "200":
          description: JSON index
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
    PlatPhormBearer:
      type: http
      scheme: bearer
security: []
