openapi: 3.1.0
info:
  title: Site Brief
  version: 1.0.0
  summary: Paid website metadata and agent-readiness briefs for AI agents.
  description: >
    Site Brief is a paid x402 API that turns a public URL into compact website
    metadata, headings, links, excerpt text, and agent-readiness signals.
  contact:
    name: Daniel Hallman
servers:
  - url: https://agentic-market-site-brief.vercel.app
    description: Production
paths:
  /:
    get:
      operationId: getProductPage
      summary: Product landing page
      responses:
        "200":
          description: HTML product page.
          content:
            text/html:
              schema:
                type: string
  /health:
    get:
      operationId: getHealth
      summary: Health and configuration status
      responses:
        "200":
          description: Service health status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /api/site-brief:
    get:
      operationId: getSiteBrief
      summary: Get a paid Site Brief for a public URL
      description: >
        Paid x402 endpoint. An unpaid request returns HTTP 402 with a
        PAYMENT-REQUIRED challenge. An x402-compatible client pays and retries
        with X-PAYMENT.
      parameters:
        - name: url
          in: query
          required: true
          description: Public http or https URL to analyze.
          schema:
            type: string
            format: uri
            example: https://example.com
      responses:
        "200":
          description: Site brief result.
          headers:
            X-PAYMENT-RESPONSE:
              description: x402 payment settlement response, when returned by the facilitator.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SiteBrief"
        "400":
          description: Missing or invalid URL.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "402":
          description: x402 payment required.
          headers:
            PAYMENT-REQUIRED:
              description: Base64-encoded x402 payment challenge.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
        "415":
          description: Unsupported upstream content type.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Upstream fetch failed.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Service is missing seller configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - x402Payment: []
  /mcp:
    get:
      operationId: getMcpInfo
      summary: MCP endpoint information
      responses:
        "200":
          description: MCP endpoint summary and server card.
          content:
            application/json:
              schema:
                type: object
    post:
      operationId: postMcpJsonRpc
      summary: MCP JSON-RPC endpoint
      description: Supports initialize, notifications/initialized, tools/list, and tools/call for the site_brief tool.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/JsonRpcRequest"
      responses:
        "200":
          description: JSON-RPC response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JsonRpcResponse"
  /llms.txt:
    get:
      operationId: getLlmsTxt
      summary: Agent-readable product instructions
      responses:
        "200":
          description: llms.txt content.
          content:
            text/plain:
              schema:
                type: string
components:
  securitySchemes:
    x402Payment:
      type: apiKey
      in: header
      name: X-PAYMENT
      description: x402 payment payload returned by an x402-compatible client after reading PAYMENT-REQUIRED.
  schemas:
    Health:
      type: object
      properties:
        ok:
          type: boolean
        service:
          type: string
        configured:
          type: boolean
        network:
          type: string
        facilitatorUrl:
          type: string
        resourceUrl:
          type:
            - string
            - "null"
        unpaidLocalBypass:
          type: boolean
      required:
        - ok
        - service
        - configured
        - network
    SiteBrief:
      type: object
      properties:
        requestedUrl:
          type: string
          format: uri
        finalUrl:
          type: string
          format: uri
        fetchedAt:
          type: string
          format: date-time
        elapsedMs:
          type: integer
        contentType:
          type: string
        title:
          type: string
        description:
          type: string
        headings:
          type: array
          items:
            type: string
        links:
          type: array
          items:
            type: object
            properties:
              text:
                type: string
              href:
                type: string
                format: uri
            required:
              - text
              - href
        agentSignals:
          type: object
          properties:
            hasPricingLanguage:
              type: boolean
            hasDocsLanguage:
              type: boolean
            hasApiLanguage:
              type: boolean
            hasContactLanguage:
              type: boolean
          required:
            - hasPricingLanguage
            - hasDocsLanguage
            - hasApiLanguage
            - hasContactLanguage
        excerpt:
          type: string
      required:
        - requestedUrl
        - finalUrl
        - fetchedAt
        - elapsedMs
        - contentType
        - title
        - description
        - headings
        - links
        - agentSignals
        - excerpt
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
    JsonRpcRequest:
      type: object
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          type:
            - string
            - integer
            - "null"
        method:
          type: string
        params:
          type: object
      required:
        - jsonrpc
        - method
    JsonRpcResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          const: "2.0"
        id:
          type:
            - string
            - integer
            - "null"
        result:
          type: object
        error:
          type: object
