openapi: 3.1.0
info:
  title: Aegis AI on ai4ciso.ai — Buyer-Agent API
  version: "1.0.0"
  description: |
    Read endpoints + checkout helper for AI buyer agents purchasing vCISO offerings from
    Aegis AI / ElasticD3M, LLC. The actual payment is performed at the offer's `checkout_url`
    (a Stripe Payment Link). For agent-to-agent procurement coordination, email
    agents@ai4ciso.ai with subject prefix [AGENT-PURCHASE].
  contact:
    email: agents@ai4ciso.ai
servers:
  - url: https://platform.ai4ciso.ai
  - url: https://ai4ciso.ai
paths:
  /api/v1/ciso/agents/offers:
    get:
      operationId: listOffers
      summary: Fetch the full offer catalog.
      description: |
        Returns the array of all purchasable offers with direct Stripe Payment Link checkout URLs.
      responses:
        "200":
          description: Offer catalog.
          content:
            application/json:
              schema:
                type: object
                properties:
                  offers:
                    type: array
                    items: {$ref: "#/components/schemas/Offer"}
  /api/v1/ciso/agents/offers/{offer_id}:
    get:
      operationId: getOffer
      summary: Fetch a single offer by id.
      parameters:
        - in: path
          name: offer_id
          required: true
          schema: {type: string}
          example: sentinel-monthly
      responses:
        "200":
          description: Offer.
          content:
            application/json:
              schema: {$ref: "#/components/schemas/Offer"}
        "404":
          description: Offer not found.
  /api/v1/ciso/agents/checkout:
    post:
      operationId: createCheckout
      summary: Generate a Stripe Payment Link prefilled with the buyer's email.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [offer_id, email]
              properties:
                offer_id: {type: string, example: sentinel-monthly}
                email: {type: string, format: email, example: buyer@example.com}
                buyer_agent_id: {type: string, nullable: true, description: "Optional. Identifier of the buyer-agent initiating the purchase."}
      responses:
        "200":
          description: Stripe Payment Link URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  checkout_url: {type: string, format: uri}
                  offer_id: {type: string}
        "400":
          description: Invalid offer_id or email.
  /api/v1/ciso/agents/health:
    get:
      operationId: getHealth
      summary: Liveness probe.
      responses:
        "200":
          description: Service is live.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status: {type: string, example: ok}
                  ts: {type: string, format: date-time}
  /products.json:
    get:
      operationId: getProductFeed
      summary: Static product/offer feed (mirror of /api/v1/ciso/agents/offers).
      responses:
        "200":
          description: Product feed.
          content:
            application/json:
              schema:
                type: object
  /llms.txt:
    get:
      operationId: getLLMsBrief
      summary: Plain-language brief for LLMs and AI agents.
      responses:
        "200":
          description: Markdown brief.
          content:
            text/plain: {}
  /agents:
    get:
      operationId: getAgentsProtocol
      summary: Human- and agent-readable buyer protocol page.
      responses:
        "200":
          description: HTML page describing the buyer-agent protocol.
          content:
            text/html: {}
components:
  schemas:
    Offer:
      type: object
      required: [id, name, price_usd, currency, checkout_url, type]
      properties:
        id: {type: string}
        name: {type: string}
        description: {type: string}
        category: {type: string}
        type: {type: string, enum: [one_time, subscription]}
        billing_cycle: {type: string, enum: [monthly, annual], nullable: true}
        price_usd: {type: number}
        currency: {type: string, example: USD}
        checkout_url: {type: string, format: uri}
        sku: {type: string}
        metadata:
          type: object
          properties:
            lob: {type: string, example: ai4ciso}
