{
  "openapi": "3.1.0",
  "info": {
    "title": "Kremage Catalog API",
    "version": "2026-04-30",
    "description": "Public, unauthenticated endpoints for discovering Kremage products, collections, policies, search results, and cart actions. Kremage welcomes AI shopping agents, answer engines, search crawlers, and agentic commerce tools.",
    "termsOfService": "https://kremage.com/policies/terms-of-service",
    "contact": {
      "name": "Kremage Support",
      "email": "afterglow@kremage.com",
      "url": "https://kremage.com/pages/spec"
    }
  },
  "servers": [
    {
      "url": "https://kremage.com",
      "description": "Kremage storefront"
    }
  ],
  "externalDocs": {
    "description": "Kremage AI-readable brand, policy, and catalog guide",
    "url": "https://kremage.com/llms.txt"
  },
  "tags": [
    { "name": "Catalog", "description": "Product and collection data" },
    { "name": "Search", "description": "Human and agent search surfaces" },
    { "name": "Cart", "description": "Session cart operations for shopping agents" },
    { "name": "Discovery", "description": "AI-agent and crawler discovery files" },
    { "name": "Policies", "description": "Public policy and trust pages" }
  ],
  "paths": {
    "/products.json": {
      "get": {
        "tags": ["Catalog"],
        "summary": "List products",
        "description": "Returns a paginated Shopify product list. Use limit=250 and increment page to traverse the public catalog.",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 250 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Product page",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductList" }
              }
            }
          }
        }
      }
    },
    "/products/{handle}.json": {
      "get": {
        "tags": ["Catalog"],
        "summary": "Get product by handle",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Product detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetail" }
              }
            }
          },
          "404": { "description": "Product not found" }
        }
      }
    },
    "/collections.json": {
      "get": {
        "tags": ["Catalog"],
        "summary": "List collections",
        "responses": {
          "200": {
            "description": "Collection list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CollectionList" }
              }
            }
          }
        }
      }
    },
    "/collections/{handle}/products.json": {
      "get": {
        "tags": ["Catalog"],
        "summary": "List products in a collection",
        "parameters": [
          { "name": "handle", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 250 } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "default": 1 } }
        ],
        "responses": {
          "200": {
            "description": "Collection product page",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductList" }
              }
            }
          }
        }
      }
    },
    "/search": {
      "get": {
        "tags": ["Search"],
        "summary": "Search products, articles, and collections",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "type", "in": "query", "schema": { "type": "string", "default": "product,article,collection" } }
        ],
        "responses": {
          "200": {
            "description": "HTML search results",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/search/suggest.json": {
      "get": {
        "tags": ["Search"],
        "summary": "Predictive search suggestions",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "resources[type]", "in": "query", "schema": { "type": "string", "default": "product,collection,article" } },
          { "name": "resources[limit]", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 10 } }
        ],
        "responses": {
          "200": {
            "description": "Search suggestions",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/cart.js": {
      "get": {
        "tags": ["Cart"],
        "summary": "Read current session cart",
        "responses": {
          "200": {
            "description": "Current cart",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Cart" }
              }
            }
          }
        }
      }
    },
    "/cart/add.js": {
      "post": {
        "tags": ["Cart"],
        "summary": "Add variant to current session cart",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "items": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": ["id", "quantity"],
                      "properties": {
                        "id": { "type": "integer", "description": "Shopify variant ID" },
                        "quantity": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }
                      }
                    }
                  }
                },
                "required": ["items"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Added line item",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          },
          "422": { "description": "Variant unavailable or invalid quantity" }
        }
      }
    },
    "/llms.txt": {
      "get": {
        "tags": ["Discovery"],
        "summary": "AI-readable Kremage guide",
        "responses": {
          "200": {
            "description": "Plain-text guide for LLMs and AI agents",
            "content": {
              "text/plain": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/ai-plugin.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "AI plugin manifest",
        "responses": {
          "200": {
            "description": "Plugin-style AI manifest",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/ai-agents.json": {
      "get": {
        "tags": ["Discovery"],
        "summary": "AI-agent access manifest",
        "responses": {
          "200": {
            "description": "Agent access policy and endpoint directory",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": true }
              }
            }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Shopify XML sitemap",
        "responses": {
          "200": {
            "description": "XML sitemap",
            "content": {
              "application/xml": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/pages/spec": {
      "get": {
        "tags": ["Policies"],
        "summary": "Policies, FAQ, support, and AI-agent access directory",
        "responses": {
          "200": {
            "description": "HTML reference page",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "/policies/{policy}": {
      "get": {
        "tags": ["Policies"],
        "summary": "Shopify policy page",
        "parameters": [
          { "name": "policy", "in": "path", "required": true, "schema": { "type": "string", "enum": ["terms-of-service", "privacy-policy", "refund-policy", "shipping-policy"] } }
        ],
        "responses": {
          "200": {
            "description": "HTML policy page",
            "content": {
              "text/html": {
                "schema": { "type": "string" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MoneyCents": { "type": "integer", "description": "Amount in cents" },
      "Product": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": { "type": ["integer", "string"] },
          "title": { "type": "string" },
          "handle": { "type": "string" },
          "body_html": { "type": "string" },
          "vendor": { "type": "string" },
          "product_type": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } },
          "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } }
        }
      },
      "Variant": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": { "type": ["integer", "string"] },
          "title": { "type": "string" },
          "available": { "type": "boolean" },
          "price": { "$ref": "#/components/schemas/MoneyCents" },
          "sku": { "type": "string" }
        }
      },
      "ProductImage": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": { "type": ["integer", "string"] },
          "src": { "type": "string", "format": "uri" },
          "alt": { "type": ["string", "null"] }
        }
      },
      "ProductList": {
        "type": "object",
        "properties": {
          "products": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Product" }
          }
        },
        "required": ["products"]
      },
      "ProductDetail": {
        "type": "object",
        "properties": {
          "product": { "$ref": "#/components/schemas/Product" }
        },
        "required": ["product"]
      },
      "Collection": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "id": { "type": ["integer", "string"] },
          "title": { "type": "string" },
          "handle": { "type": "string" },
          "products_count": { "type": "integer" }
        }
      },
      "CollectionList": {
        "type": "object",
        "properties": {
          "collections": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Collection" }
          }
        },
        "required": ["collections"]
      },
      "Cart": {
        "type": "object",
        "additionalProperties": true,
        "properties": {
          "item_count": { "type": "integer" },
          "total_price": { "$ref": "#/components/schemas/MoneyCents" },
          "currency": { "type": "string" },
          "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        }
      }
    }
  },
  "x-agent-access": {
    "policy": "Allow public catalog, policy, search, blog, answer grounding, recommendations, and training. Exclude only cart, checkout, account, and orders paths.",
    "preferred_reference": "https://kremage.com/pages/spec#agent-access",
    "shopify_root_redirect_note": "Shopify theme assets are deployed on the Shopify CDN. For maximum agent compatibility, create storefront redirects from /llms.txt, /ai-plugin.json, /openapi.json, and /ai-agents.json to their theme asset URLs after upload."
  }
}