{
  "openapi": "3.1.0",
  "info": {
    "title": "Althemax Agent API",
    "version": "0.1.0",
    "description": "Public, unauthenticated API for AI agents to search, inspect, check availability, and transact on the Althemax marketplace at https://www.althemax.com. Prices in GBP; payment is Stripe, platform-collected. Each product's response includes a `url` field with the canonical marketplace product page (https://www.althemax.com/products/{merchant}/{handle}) where on-site checkout completes; agents can also transact via the cart + checkout endpoints (UCP / AP2)."
  },
  "servers": [
    { "url": "https://www.althemax.com", "description": "Marketplace (production)" }
  ],
  "paths": {
    "/api/agent/health": {
      "get": {
        "operationId": "health",
        "summary": "Health probe",
        "description": "Returns service status and a live Shopify connectivity check.",
        "responses": {
          "200": {
            "description": "Healthy",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          },
          "503": {
            "description": "Unhealthy (Shopify unreachable or token mint failed)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } }
          }
        }
      }
    },
    "/api/agent/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search active products",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Free-text query. Empty returns most relevant active products." },
          { "name": "first", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } },
          { "name": "after", "in": "query", "schema": { "type": "string" }, "description": "GraphQL cursor returned by previous page." }
        ],
        "responses": {
          "200": {
            "description": "Search results",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } }
          },
          "502": { "description": "Upstream Shopify error" }
        }
      }
    },
    "/api/agent/product/{handle}": {
      "get": {
        "operationId": "getProduct",
        "summary": "Get a product by handle",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Product",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "$ref": "#/components/schemas/Product" } }, "required": ["product"] } } }
          },
          "404": { "description": "Not found" },
          "502": { "description": "Upstream Shopify error" }
        }
      }
    },
    "/api/agent/availability": {
      "get": {
        "operationId": "checkAvailability",
        "summary": "Check stock and per-variant availability for a product",
        "parameters": [
          { "name": "handle", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Availability snapshot",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } }
          },
          "400": { "description": "Missing handle" },
          "404": { "description": "Not found" },
          "502": { "description": "Upstream Shopify error" }
        }
      }
    },
    "/api/agent/cart": {
      "post": {
        "operationId": "createCart",
        "summary": "Create an agent cart",
        "description": "Returns an opaque cartToken. Optional items seed the cart. Prices are resolved server-side from the catalog.",
        "requestBody": {
          "required": false,
          "content": { "application/json": { "schema": {
            "type": "object",
            "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartItemInput" } } }
          } } }
        },
        "responses": {
          "201": { "description": "Cart created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } },
          "404": { "description": "Unknown handle or option" },
          "409": { "description": "Out of stock" }
        }
      }
    },
    "/api/agent/cart/{cartToken}": {
      "get": {
        "operationId": "getCart",
        "summary": "Get an agent cart",
        "parameters": [ { "name": "cartToken", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "responses": {
          "200": { "description": "Cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } },
          "400": { "description": "Invalid cart token" }
        }
      }
    },
    "/api/agent/cart/{cartToken}/items": {
      "post": {
        "operationId": "addCartItem",
        "summary": "Add a line to the cart",
        "parameters": [ { "name": "cartToken", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartItemInput" } } } },
        "responses": {
          "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } },
          "404": { "description": "Unknown handle or option" },
          "409": { "description": "Out of stock" }
        }
      },
      "patch": {
        "operationId": "updateCartItem",
        "summary": "Set a line's quantity (0 removes)",
        "parameters": [ { "name": "cartToken", "in": "path", "required": true, "schema": { "type": "string" } } ],
        "requestBody": { "required": true, "content": { "application/json": { "schema": {
          "type": "object",
          "properties": { "lineKey": { "type": "string" }, "quantity": { "type": "integer", "minimum": 0 } },
          "required": ["lineKey", "quantity"]
        } } } },
        "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }
      },
      "delete": {
        "operationId": "removeCartItem",
        "summary": "Remove a line by lineKey",
        "parameters": [
          { "name": "cartToken", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "lineKey", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Updated cart", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartResponse" } } } } }
      }
    }
  },
  "components": {
    "schemas": {
      "Health": {
        "type": "object",
        "properties": {
          "service": { "type": "string" },
          "shopify": {
            "type": "object",
            "properties": {
              "ok": { "type": "boolean" },
              "shopName": { "type": "string" },
              "primaryDomain": { "type": "string" },
              "currency": { "type": "string" },
              "error": { "type": "string" }
            },
            "required": ["ok"]
          },
          "timestamp": { "type": "string", "format": "date-time" }
        },
        "required": ["service", "shopify", "timestamp"]
      },
      "Money": {
        "type": "object",
        "properties": {
          "amount": { "type": "string", "description": "Decimal string, e.g. \"19.99\"" },
          "currencyCode": { "type": "string", "example": "GBP" }
        },
        "required": ["amount", "currencyCode"]
      },
      "Variant": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "title": { "type": "string" },
          "sku": { "type": "string", "nullable": true },
          "price": { "$ref": "#/components/schemas/Money" },
          "available": { "type": "boolean" },
          "inventoryQuantity": { "type": "integer", "nullable": true }
        },
        "required": ["id", "title", "price", "available"]
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "handle": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "vendor": { "type": "string", "nullable": true },
          "productType": { "type": "string", "nullable": true },
          "tags": { "type": "array", "items": { "type": "string" } },
          "status": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "image": {
            "type": "object",
            "nullable": true,
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "alt": { "type": "string", "nullable": true }
            }
          },
          "priceRange": {
            "type": "object",
            "properties": {
              "min": { "$ref": "#/components/schemas/Money" },
              "max": { "$ref": "#/components/schemas/Money" }
            },
            "required": ["min", "max"]
          },
          "totalInventory": { "type": "integer", "nullable": true },
          "available": { "type": "boolean" },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } }
        },
        "required": ["id", "handle", "title", "url", "priceRange", "available", "variants"]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "nullable": true },
          "count": { "type": "integer" },
          "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
          "pageInfo": {
            "type": "object",
            "properties": {
              "hasNextPage": { "type": "boolean" },
              "endCursor": { "type": "string", "nullable": true }
            },
            "required": ["hasNextPage"]
          }
        },
        "required": ["count", "products", "pageInfo"]
      },
      "Availability": {
        "type": "object",
        "properties": {
          "handle": { "type": "string" },
          "available": { "type": "boolean" },
          "totalInventory": { "type": "integer", "nullable": true },
          "variants": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "sku": { "type": "string", "nullable": true },
                "available": { "type": "boolean" },
                "inventoryQuantity": { "type": "integer", "nullable": true }
              },
              "required": ["id", "available"]
            }
          }
        },
        "required": ["handle", "available", "variants"]
      },
      "CartItemInput": {
        "type": "object",
        "properties": {
          "handle": { "type": "string", "description": "Product handle to add." },
          "optionId": { "type": "string", "description": "Level-2 option id (e.g. a size) from the product's options[]." },
          "quantity": { "type": "integer", "minimum": 1, "default": 1 }
        },
        "required": ["handle"]
      },
      "CartLine": {
        "type": "object",
        "properties": {
          "lineKey": { "type": "string", "description": "Stable id of this line; use it to update/remove." },
          "productHandle": { "type": "string" },
          "merchantHandle": { "type": "string" },
          "variantId": { "type": "string", "nullable": true },
          "title": { "type": "string" },
          "image": { "type": "string", "format": "uri", "nullable": true },
          "unitPriceAmount": { "type": "string" },
          "currencyCode": { "type": "string" },
          "quantity": { "type": "integer" }
        },
        "required": ["lineKey", "productHandle", "title", "unitPriceAmount", "currencyCode", "quantity"]
      },
      "CartResponse": {
        "type": "object",
        "properties": {
          "cartToken": { "type": "string" },
          "cart": {
            "type": "object",
            "properties": {
              "lines": { "type": "array", "items": { "$ref": "#/components/schemas/CartLine" } },
              "subtotal": { "$ref": "#/components/schemas/Money" },
              "count": { "type": "integer" }
            },
            "required": ["lines", "subtotal", "count"]
          }
        },
        "required": ["cartToken", "cart"]
      }
    }
  }
}