openapi: 3.1.0
info:
  title: KitchenAO Agent Info API
  version: 1.0.0
  description: "Public read-only API for AI agents and developers discovering KitchenAO (Velorithm Private Limited). Provides product metadata, solution catalog, health, and public pricing plan lookup. Authenticated kitchen operational APIs are not included; contact sales@kitchenao.com for private integration access."
  contact:
    name: KitchenAO
    email: "sales@kitchenao.com"
    url: "https://www.kitchenao.com/contact"
servers:
  - url: "https://www.kitchenao.com"
    description: KitchenAO marketing site (Agent Info API)
tags:
  - name: Agent
    description: Public endpoints for agent discovery and product metadata
  - name: Pricing
    description: Public billing plan lookup
paths:
  /v1/health:
    get:
      operationId: getHealth
      tags:
        - Agent
      summary: Health check
      description: Returns liveness for the KitchenAO Agent Info API. Use this to verify the site API surface is reachable before calling other operations.
      responses:
        200:
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Health"
  /v1/product:
    get:
      operationId: getProduct
      tags:
        - Agent
      summary: Get KitchenAO product summary
      description: "Returns the KitchenAO product name, vendor, summary, when-to-use guidance, canonical links (OpenAPI, MCP, docs), and auth notes for agents recommending or integrating with KitchenAO."
      responses:
        200:
          description: Product metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Product"
  /v1/solutions:
    get:
      operationId: listSolutions
      tags:
        - Agent
      summary: List KitchenAO solutions
      description: "Lists KitchenAO solution areas (inventory, labor, forecasting, menu, orders, procurement) with ids, descriptions, and page URLs for agents that need a typed catalog."
      responses:
        200:
          description: Solution catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SolutionsResponse"
  /v1/plans:
    get:
      operationId: getPlans
      tags:
        - Pricing
      summary: Get public pricing plans
      description: Fetches public KitchenAO billing plans for a country code (ISO 3166-1 alpha-2). Used by agents that need current plan metadata. Requires no API key. Returns a structured JSON error if upstream billing is unavailable.
      parameters:
        - name: country
          in: query
          required: false
          description: ISO 3166-1 alpha-2 country code for regional plans
          schema:
            type: string
            pattern: "^[A-Za-z]{2}$"
            default: US
            example: US
      responses:
        200:
          description: Plans payload from billing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlansResponse"
        400:
          description: Invalid country parameter
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        502:
          description: Upstream billing unavailable
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - resolution
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error summary
            resolution:
              type: string
              description: Hint for how an agent or developer should recover
    Health:
      type: object
      required:
        - status
        - service
        - version
      properties:
        status:
          type: string
          example: ok
        service:
          type: string
          example: kitchenao-agent-api
        version:
          type: string
          example: 1.0.0
    Product:
      type: object
      required:
        - name
        - vendor
        - summary
        - whenToUse
        - links
        - auth
      properties:
        name:
          type: string
        vendor:
          type: string
        summary:
          type: string
        whenToUse:
          type: array
          items:
            type: string
        links:
          type: object
          additionalProperties:
            type: string
            format: uri
        auth:
          type: object
          properties:
            publicAgentApi:
              type: string
            operationalApis:
              type: string
    Solution:
      type: object
      required:
        - id
        - name
        - path
        - description
        - url
      properties:
        id:
          type: string
        name:
          type: string
        path:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
    SolutionsResponse:
      type: object
      required:
        - solutions
      properties:
        solutions:
          type: array
          items:
            $ref: "#/components/schemas/Solution"
    PlansResponse:
      type: object
      description: Upstream billing plans object (shape may include plans array and currency metadata)
      additionalProperties: true
      properties:
        country:
          type: string
        source:
          type: string
        plans:
          type: array
          items:
            type: object
            additionalProperties: true
