{
  "openapi": "3.1.0",
  "info": {
    "title": "Momy & Co Storefront Data API",
    "version": "2026-08-24",
    "summary": "Public, read-first HTTP API for the Momy & Co online store (childrenswear, washable rugs, nursery and home decor, Brazil).",
    "description": "Machine-readable description of every public endpoint exposed by the Momy & Co storefront at https://www.momyco.com.br.\n\n**When to use this API.** Reach for it when you need to read the Momy & Co catalog (products, variants, prices in BRL, stock availability, collections), run a product search, build a cart, or hand a shopper off to checkout. Catalog and search endpoints need no authentication and no account. Anything that reads or writes a specific customer's data requires OAuth 2.0 (see `customerAccountOAuth`).\n\n**When NOT to use it.** This is a single-merchant retail storefront, not a multi-tenant SaaS platform. There is no admin/back-office surface here, no way to create products, and no server-to-server bulk export. For agent-driven purchasing across many Shopify stores, prefer the Universal Commerce Protocol (UCP) MCP endpoint documented under `/api/ucp/mcp`, or the Shop skill at https://shop.app/SKILL.md.\n\n**Money.** Every `*.js` / `*.json` storefront endpoint returns prices as integers in BRL cents (`221765` = R$ 2.217,65). The UCP/MCP endpoint returns `{\"amount\": 221765, \"currency\": \"BRL\"} (integer minor units)`. Divide by 100 before quoting a price to a buyer.\n\n**Errors.** Failing requests return `application/json` with the shape described by `ErrorResponse`. See the `x-error-catalog` extension for the codes an agent can expect and how to recover from each.\n\n**Rate limits.** The storefront is rate limited per IP. Back off on `429` and honour `Retry-After`. Keep catalog crawls under roughly 2 requests/second and prefer the paginated `products.json` endpoints over crawling HTML pages.",
    "termsOfService": "https://www.momyco.com.br/policies/terms-of-service",
    "contact": {
      "name": "Momy & Co developer contact",
      "url": "https://www.momyco.com.br/pages/developers"
    },
    "license": {
      "name": "Proprietary. Catalog data may be read by agents acting for a shopper; redistribution requires permission.",
      "url": "https://www.momyco.com.br/policies/terms-of-service"
    },
    "x-agent-guidance": {
      "best-fit-jobs": [
        "Find washable rugs, nursery decor, kids' furniture, playmats or gifts sold in Brazil, filtered by size, room or brand.",
        "Look up a specific Momy & Co product's live price, installment terms and stock availability before recommending it.",
        "Build a cart and start a checkout on behalf of a shopper who has explicitly asked to buy from Momy & Co.",
        "Answer questions about shipping, returns, exchanges and payment options for orders placed in Brazil."
      ],
      "poor-fit-jobs": [
        "Bulk-scraping the catalog for price intelligence. Use the paginated JSON endpoints and respect the rate limits.",
        "Completing a payment without a human in the loop. Checkout always requires contemporaneous buyer approval.",
        "Anything requiring merchant or admin privileges. That surface is not public."
      ],
      "zero-auth-surface": [
        "/collections.json",
        "/collections/{collection_handle}/products.json",
        "/products/{product_handle}.json",
        "/search/suggest.json",
        "/recommendations/products.json",
        "/cart.js",
        "/.well-known/ucp"
      ],
      "human-approval-required": [
        "POST /api/ucp/mcp with method tools/call and name complete_checkout",
        "/checkout"
      ]
    },
    "x-error-catalog": [
      {
        "status": 404,
        "message": "Not Found",
        "meaning": "The handle or id does not exist, or the resource is not published to the online store.",
        "recovery": "Re-resolve the handle via /search/suggest.json or /collections/{handle}/products.json before retrying."
      },
      {
        "status": 422,
        "message": "Cart Error",
        "meaning": "The cart mutation was rejected, most often an unknown or unavailable variant id.",
        "recovery": "Refetch the product with /products/{handle}.json, pick an available variant id, retry once."
      },
      {
        "status": 429,
        "message": "Too Many Requests",
        "meaning": "Per-IP rate limit exceeded.",
        "recovery": "Honour Retry-After, apply exponential backoff, and reduce concurrency to at most 2 requests per second."
      },
      {
        "status": 430,
        "message": "Shopify Security Rejection",
        "meaning": "The request was flagged as automated abuse.",
        "recovery": "Send a descriptive User-Agent identifying your agent and slow down. Do not rotate IPs to evade the block."
      }
    ]
  },
  "servers": [
    { "url": "https://www.momyco.com.br", "description": "Production storefront (primary domain)" },
    { "url": "https://1xe1kt-63.myshopify.com", "description": "Canonical Shopify origin, same data, used by UCP discovery" }
  ],
  "externalDocs": {
    "description": "Momy & Co agent instructions: when-to-use guidance, protocols, policies",
    "url": "https://www.momyco.com.br/agents.md"
  },
  "security": [{ "publicRead": [] }],
  "tags": [
    { "name": "catalog", "description": "Read products and collections. No authentication." },
    { "name": "search", "description": "Query the catalog. No authentication." },
    { "name": "cart", "description": "Build and mutate an anonymous cart bound to a session cookie." },
    { "name": "discovery", "description": "Machine-readable descriptions of the store itself." },
    { "name": "agent-protocols", "description": "UCP and MCP surfaces for agent-driven commerce." }
  ],
  "paths": {
    "/collections.json": {
      "get": {
        "operationId": "listCollections",
        "summary": "List published collections",
        "description": "Returns every collection published to the online store, with handle, title, description and product count. Use the returned handle with listCollectionProducts.",
        "tags": ["catalog"],
        "security": [{ "publicRead": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Page" }
        ],
        "responses": {
          "200": {
            "description": "Collection list.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionList" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/collections/{collection_handle}/products.json": {
      "get": {
        "operationId": "listCollectionProducts",
        "summary": "List products in a collection",
        "description": "Paginated product listing for one collection. Use the reserved handle `all` to page through the entire catalog. Prices are integers in BRL cents.",
        "tags": ["catalog"],
        "security": [{ "publicRead": [] }],
        "parameters": [
          { "$ref": "#/components/parameters/CollectionHandle" },
          { "$ref": "#/components/parameters/Limit" },
          { "$ref": "#/components/parameters/Page" }
        ],
        "responses": {
          "200": {
            "description": "Product page for the collection.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/products/{product_handle}.json": {
      "get": {
        "operationId": "getProductByHandle",
        "summary": "Get one product by handle",
        "description": "Full product record: title, HTML description, vendor, product type, tags, images and every variant with price, SKU and availability. This is the authoritative price source; do not infer prices from rendered HTML.",
        "tags": ["catalog"],
        "security": [{ "publicRead": [] }],
        "parameters": [{ "$ref": "#/components/parameters/ProductHandle" }],
        "responses": {
          "200": {
            "description": "The product.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductEnvelope" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/search/suggest.json": {
      "get": {
        "operationId": "searchCatalog",
        "summary": "Search products, collections, pages and articles",
        "description": "Predictive search across the storefront. Query in Portuguese for best recall (tapete, almofada, cesto, berco). Returns the same product shape as the catalog endpoints.",
        "tags": ["search"],
        "security": [{ "publicRead": [] }],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Free-text query. Portuguese terms match best.",
            "schema": { "type": "string", "minLength": 1, "maxLength": 200 },
            "example": "tapete lavavel"
          },
          {
            "name": "resources[type]",
            "in": "query",
            "required": false,
            "description": "Comma-separated resource types to search.",
            "schema": {
              "type": "string",
              "default": "product",
              "pattern": "^(product|collection|page|article)(,(product|collection|page|article))*$"
            },
            "example": "product,collection"
          },
          {
            "name": "resources[limit]",
            "in": "query",
            "required": false,
            "description": "Maximum results per resource type.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 5 }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results grouped by resource type.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/recommendations/products.json": {
      "get": {
        "operationId": "listProductRecommendations",
        "summary": "Get products related to a given product",
        "description": "Complementary and related products for one product id. Useful for building a room set or a gift bundle.",
        "tags": ["catalog"],
        "security": [{ "publicRead": [] }],
        "parameters": [
          {
            "name": "product_id",
            "in": "query",
            "required": true,
            "description": "Numeric product id (not the handle), taken from any catalog response.",
            "schema": { "type": "integer", "format": "int64" },
            "example": 15358932844868
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum recommendations to return.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 4 }
          },
          {
            "name": "intent",
            "in": "query",
            "required": false,
            "description": "`related` for similar items, `complementary` for items bought together.",
            "schema": { "type": "string", "enum": ["related", "complementary"], "default": "related" }
          }
        ],
        "responses": {
          "200": {
            "description": "Recommended products.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductList" } } }
          },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/cart.js": {
      "get": {
        "operationId": "getCart",
        "summary": "Read the current cart",
        "description": "Returns the cart bound to the caller's session cookie. An agent with no cookie jar receives an empty cart. Persist cookies across cart calls.",
        "tags": ["cart"],
        "security": [{ "sessionCookie": [] }, { "publicRead": [] }],
        "responses": {
          "200": {
            "description": "The current cart.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } }
          }
        }
      }
    },
    "/cart/add.js": {
      "post": {
        "operationId": "addCartItems",
        "summary": "Add variants to the cart",
        "description": "Adds one or more variants. Requires a variant id from getProductByHandle, not a product id. Returns 422 with an ErrorResponse body when the variant is unknown or unavailable.",
        "tags": ["cart"],
        "security": [{ "sessionCookie": [] }, { "publicRead": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartAddRequest" } } }
        },
        "responses": {
          "200": {
            "description": "The line items that were added.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartAddResponse" } } }
          },
          "422": { "$ref": "#/components/responses/UnprocessableCart" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/cart/change.js": {
      "post": {
        "operationId": "changeCartLine",
        "summary": "Change the quantity of one cart line",
        "description": "Set quantity to 0 to remove a line. Identify the line by its `key` (preferred) or its 1-based `line` index.",
        "tags": ["cart"],
        "security": [{ "sessionCookie": [] }, { "publicRead": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CartChangeRequest" } } }
        },
        "responses": {
          "200": {
            "description": "The updated cart.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } }
          },
          "422": { "$ref": "#/components/responses/UnprocessableCart" }
        }
      }
    },
    "/cart/clear.js": {
      "post": {
        "operationId": "clearCart",
        "summary": "Remove every line from the cart",
        "description": "Empties the session cart and returns the resulting empty cart object.",
        "tags": ["cart"],
        "security": [{ "sessionCookie": [] }, { "publicRead": [] }],
        "responses": {
          "200": {
            "description": "The now-empty cart.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Cart" } } }
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemapIndex",
        "summary": "Sitemap index",
        "description": "XML sitemap index linking per-resource sitemaps for products, collections, pages and blog articles.",
        "tags": ["discovery"],
        "security": [{ "publicRead": [] }],
        "responses": {
          "200": {
            "description": "Sitemap index.",
            "content": { "application/xml": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/agents.md": {
      "get": {
        "operationId": "getAgentInstructions",
        "summary": "Agent instructions with when-to-use guidance",
        "description": "Markdown document describing what this store is for, when an agent should use it, and every protocol it speaks. The same document is served at /llms.txt and /llms-full.txt.",
        "tags": ["discovery"],
        "security": [{ "publicRead": [] }],
        "responses": {
          "200": {
            "description": "Agent instructions.",
            "content": { "text/markdown": { "schema": { "type": "string" } } }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "summary": "This document",
        "description": "The OpenAPI 3.1 description of the Momy & Co storefront API. Redirects to /pages/openapi, which serves the raw JSON body.",
        "tags": ["discovery"],
        "security": [{ "publicRead": [] }],
        "responses": {
          "200": {
            "description": "OpenAPI document.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/mcp.json": {
      "get": {
        "operationId": "getMcpManifest",
        "summary": "MCP server manifest",
        "description": "Manifest describing the Streamable HTTP MCP endpoint this store exposes, its transport, protocol version and tool names. Redirects to /pages/mcp, which serves the raw JSON body.",
        "tags": ["agent-protocols"],
        "security": [{ "publicRead": [] }],
        "responses": {
          "200": {
            "description": "MCP manifest.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpManifest" } } }
          }
        }
      }
    },
    "/.well-known/ucp": {
      "get": {
        "operationId": "getUcpDiscovery",
        "summary": "Universal Commerce Protocol discovery document",
        "description": "Supported UCP versions, service endpoints, capabilities and payment handlers for agent-driven commerce.",
        "tags": ["agent-protocols"],
        "security": [{ "publicRead": [] }],
        "responses": {
          "200": {
            "description": "UCP merchant profile.",
            "content": { "application/json": { "schema": { "type": "object" } } }
          }
        }
      }
    },
    "/api/ucp/mcp": {
      "post": {
        "operationId": "callMcpEndpoint",
        "summary": "MCP (Streamable HTTP) JSON-RPC endpoint",
        "description": "Model Context Protocol endpoint implementing the UCP shopping service. Call initialize, then tools/list to discover the tools: search_catalog, lookup_catalog, get_product, create_cart, get_cart, update_cart, cancel_cart, create_checkout, get_checkout, update_checkout, complete_checkout, cancel_checkout, get_order.\n\ncomplete_checkout REQUIRES contemporaneous human approval; never call it autonomously.\n\nEvery tool call must carry a `params.meta.ucp-agent.profile` URI identifying your agent. Requests without it are rejected with JSON-RPC error -32001 and HTTP 422.",
        "tags": ["agent-protocols"],
        "security": [{ "ucpAgentProfile": [] }],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC result.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } }
          },
          "422": {
            "description": "JSON-RPC error, most often a missing agent profile URI.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } } }
          },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "publicRead": {
        "type": "apiKey",
        "in": "header",
        "name": "User-Agent",
        "description": "No credential is required for catalog, search and cart endpoints. Send a descriptive User-Agent identifying your agent and an operator contact URL so we can reach you instead of blocking you. Least privilege: this is the only access level needed to browse and price the catalog."
      },
      "sessionCookie": {
        "type": "apiKey",
        "in": "cookie",
        "name": "cart",
        "description": "Anonymous cart session. Set automatically by the first /cart/*.js call; persist and resend the cookie jar for subsequent cart calls. Carries no customer identity."
      },
      "customerAccountOAuth": {
        "type": "oauth2",
        "description": "OAuth 2.0 / OpenID Connect, required only to read or write a specific customer's own data (orders, addresses, saved payment methods). The RFC 8414 discovery document at https://shopify.com/authentication/94973002052/.well-known/openid-configuration is the machine-readable source of truth for scopes_supported. Request the narrowest scope that satisfies the task.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://shopify.com/authentication/94973002052/oauth/authorize",
            "tokenUrl": "https://shopify.com/authentication/94973002052/oauth/token",
            "refreshUrl": "https://shopify.com/authentication/94973002052/oauth/token",
            "scopes": {
              "openid": "Authenticate the customer and receive a subject identifier. Grants no profile or order access on its own.",
              "email": "Read the authenticated customer's email address.",
              "customer-account-api:full": "Read and write the authenticated customer's own account: orders, addresses, payment methods, subscriptions.",
              "customer-account-mcp-api:full": "Call the customer-scoped MCP tools on behalf of the authenticated customer."
            }
          }
        }
      },
      "storefrontAccessToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Shopify-Storefront-Access-Token",
        "description": "Optional, and only needed for the GraphQL Storefront API. Tokens are issued per integration on request via /pages/developers and are limited to unauthenticated read access: unauthenticated_read_product_listings, unauthenticated_read_product_inventory, unauthenticated_read_product_pickup_locations, unauthenticated_read_selling_plans, unauthenticated_write_checkouts. No admin scope is ever granted to a storefront token."
      },
      "ucpAgentProfile": {
        "type": "apiKey",
        "in": "header",
        "name": "X-UCP-Agent-Profile",
        "description": "Identity of the calling agent for UCP/MCP requests. In practice the profile URI travels inside the JSON-RPC body as params.meta.ucp-agent.profile; this scheme documents the requirement. Payment completion additionally requires contemporaneous buyer approval and cannot be delegated to the agent."
      }
    },
    "parameters": {
      "CollectionHandle": {
        "name": "collection_handle",
        "in": "path",
        "required": true,
        "description": "URL handle of the collection, for example `todos-os-tapetes`, `mais-vendidos`, or the reserved handle `all`.",
        "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 255 },
        "example": "todos-os-tapetes"
      },
      "ProductHandle": {
        "name": "product_handle",
        "in": "path",
        "required": true,
        "description": "URL handle of the product, taken from any catalog or search response.",
        "schema": { "type": "string", "pattern": "^[a-z0-9-]+$", "maxLength": 255 },
        "example": "abc-nude-vintage-150-cm"
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Items per page.",
        "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 30 }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "1-based page number. Stop paging when a page returns fewer than `limit` items.",
        "schema": { "type": "integer", "minimum": 1, "default": 1 }
      }
    },
    "responses": {
      "NotFound": {
        "description": "The resource does not exist or is not published to the online store.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": {
              "status": 404,
              "message": "Product not found",
              "description": "No product with id 1 is published in the online store"
            }
          }
        }
      },
      "UnprocessableCart": {
        "description": "The cart mutation was rejected.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": { "status": 422, "message": "Cart Error", "description": "Cannot find variant" }
          }
        }
      },
      "RateLimited": {
        "description": "Per-IP rate limit exceeded. Honour Retry-After and back off exponentially.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": { "type": "integer" }
          }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "title": "ErrorResponse",
        "description": "Structured error body returned by the JSON storefront endpoints.",
        "required": ["status", "message"],
        "properties": {
          "status": {
            "type": "integer",
            "description": "HTTP status code, repeated in the body for convenience.",
            "examples": [404, 422, 429]
          },
          "message": {
            "type": "string",
            "description": "Short, stable error code suitable for branching.",
            "examples": ["Cart Error", "Product not found"]
          },
          "description": {
            "type": "string",
            "description": "Human-readable explanation carrying the resolution hint."
          }
        }
      },
      "Money": {
        "type": "integer",
        "format": "int64",
        "description": "Amount in BRL cents. 221765 means R$ 2.217,65. Divide by 100 before showing it to a buyer.",
        "minimum": 0
      },
      "Variant": {
        "type": "object",
        "title": "Variant",
        "required": ["id", "title", "price", "available"],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "Variant id. This is the id /cart/add.js expects."
          },
          "title": { "type": "string", "description": "Variant name, for example the size." },
          "option1": { "type": ["string", "null"], "description": "First option value." },
          "option2": { "type": ["string", "null"], "description": "Second option value." },
          "option3": { "type": ["string", "null"], "description": "Third option value." },
          "sku": { "type": ["string", "null"], "description": "Merchant SKU." },
          "barcode": { "type": ["string", "null"], "description": "GTIN or EAN when available." },
          "price": { "$ref": "#/components/schemas/Money" },
          "compare_at_price": {
            "oneOf": [{ "$ref": "#/components/schemas/Money" }, { "type": "null" }],
            "description": "Original price when the item is on promotion. Showroom-exchange discounts are not reflected here."
          },
          "available": { "type": "boolean", "description": "Whether the variant can be purchased now." },
          "requires_shipping": { "type": "boolean", "description": "False for gift cards and digital items." },
          "taxable": { "type": "boolean", "description": "Whether tax applies to this variant." },
          "featured_image": { "type": ["object", "null"], "description": "Variant-specific image, when set." }
        }
      },
      "Product": {
        "type": "object",
        "title": "Product",
        "required": ["id", "title", "handle", "variants"],
        "properties": {
          "id": { "type": "integer", "format": "int64", "description": "Numeric product id." },
          "title": { "type": "string", "description": "Product name." },
          "handle": { "type": "string", "description": "URL handle, the key for getProductByHandle." },
          "body_html": { "type": "string", "description": "Product description as HTML." },
          "published_at": { "type": "string", "format": "date-time", "description": "When the product went live." },
          "updated_at": { "type": "string", "format": "date-time", "description": "Last modification timestamp." },
          "vendor": { "type": "string", "description": "Brand, for example Lorena Canals, Nobodinoz, Momy & Co." },
          "product_type": { "type": "string", "description": "Category, for example Tapete, Almofada, Cesto." },
          "tags": { "type": "array", "items": { "type": "string" }, "description": "Merchandising tags." },
          "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" }, "description": "Purchasable variants." },
          "images": { "type": "array", "items": { "type": "object" }, "description": "Product images." },
          "options": { "type": "array", "items": { "type": "object" }, "description": "Option definitions such as size." }
        }
      },
      "ProductEnvelope": {
        "type": "object",
        "title": "ProductEnvelope",
        "description": "Single-product response wrapper.",
        "required": ["product"],
        "properties": { "product": { "$ref": "#/components/schemas/Product" } }
      },
      "ProductList": {
        "type": "object",
        "title": "ProductList",
        "description": "Paginated product listing.",
        "required": ["products"],
        "properties": {
          "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }
        }
      },
      "Collection": {
        "type": "object",
        "title": "Collection",
        "required": ["id", "handle", "title"],
        "properties": {
          "id": { "type": "integer", "format": "int64", "description": "Numeric collection id." },
          "handle": { "type": "string", "description": "URL handle." },
          "title": { "type": "string", "description": "Collection name." },
          "description": { "type": "string", "description": "Collection description as HTML." },
          "published_at": { "type": "string", "format": "date-time", "description": "When the collection went live." },
          "updated_at": { "type": "string", "format": "date-time", "description": "Last modification timestamp." },
          "products_count": {
            "type": "integer",
            "description": "Eventually consistent. Trust the products.json listing over this number right after a catalog change."
          }
        }
      },
      "CollectionList": {
        "type": "object",
        "title": "CollectionList",
        "description": "Collection listing response.",
        "required": ["collections"],
        "properties": {
          "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }
        }
      },
      "SearchResponse": {
        "type": "object",
        "title": "SearchResponse",
        "description": "Predictive search results grouped by resource type.",
        "required": ["resources"],
        "properties": {
          "resources": {
            "type": "object",
            "required": ["results"],
            "properties": {
              "results": {
                "type": "object",
                "properties": {
                  "products": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } },
                  "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } },
                  "pages": { "type": "array", "items": { "type": "object" } },
                  "articles": { "type": "array", "items": { "type": "object" } }
                }
              }
            }
          }
        }
      },
      "CartLine": {
        "type": "object",
        "title": "CartLine",
        "description": "One line in the cart.",
        "properties": {
          "key": { "type": "string", "description": "Stable line identifier. Use this with changeCartLine." },
          "id": { "type": "integer", "format": "int64", "description": "Variant id." },
          "variant_id": { "type": "integer", "format": "int64", "description": "Variant id." },
          "product_id": { "type": "integer", "format": "int64", "description": "Parent product id." },
          "quantity": { "type": "integer", "minimum": 0, "description": "Units of this variant." },
          "title": { "type": "string", "description": "Display title for the line." },
          "price": { "$ref": "#/components/schemas/Money" },
          "line_price": { "$ref": "#/components/schemas/Money" },
          "properties": { "type": ["object", "null"], "description": "Custom line properties." }
        }
      },
      "Cart": {
        "type": "object",
        "title": "Cart",
        "description": "The session cart.",
        "required": ["item_count", "items", "currency"],
        "properties": {
          "token": { "type": "string", "description": "Cart token." },
          "item_count": { "type": "integer", "minimum": 0, "description": "Total units in the cart." },
          "total_price": { "$ref": "#/components/schemas/Money" },
          "original_total_price": { "$ref": "#/components/schemas/Money" },
          "total_discount": { "$ref": "#/components/schemas/Money" },
          "currency": { "type": "string", "const": "BRL", "description": "Always BRL for this store." },
          "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartLine" } },
          "note": { "type": ["string", "null"], "description": "Buyer note attached to the cart." }
        }
      },
      "CartAddRequest": {
        "type": "object",
        "title": "CartAddRequest",
        "description": "Body for addCartItems.",
        "required": ["items"],
        "properties": {
          "items": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": ["id", "quantity"],
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Variant id from getProductByHandle. Passing a product id returns 422."
                },
                "quantity": { "type": "integer", "minimum": 1, "description": "Units to add." },
                "properties": {
                  "type": "object",
                  "description": "Free-form line item properties such as a gift message."
                }
              }
            }
          }
        }
      },
      "CartAddResponse": {
        "type": "object",
        "title": "CartAddResponse",
        "description": "The lines created by addCartItems.",
        "required": ["items"],
        "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CartLine" } } }
      },
      "CartChangeRequest": {
        "type": "object",
        "title": "CartChangeRequest",
        "description": "Body for changeCartLine.",
        "required": ["quantity"],
        "properties": {
          "id": { "type": "string", "description": "Cart line key. Preferred over line." },
          "line": { "type": "integer", "minimum": 1, "description": "1-based line index." },
          "quantity": { "type": "integer", "minimum": 0, "description": "New quantity. 0 removes the line." }
        }
      },
      "JsonRpcRequest": {
        "type": "object",
        "title": "JsonRpcRequest",
        "description": "JSON-RPC 2.0 request for the MCP endpoint.",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0", "description": "Protocol version." },
          "id": { "type": ["string", "integer"], "description": "Correlation id." },
          "method": {
            "type": "string",
            "description": "MCP method: initialize, tools/list, tools/call, resources/list, prompts/list."
          },
          "params": {
            "type": "object",
            "description": "Method parameters. Tool calls must include meta.ucp-agent.profile.",
            "properties": {
              "meta": {
                "type": "object",
                "description": "UCP metadata envelope.",
                "properties": {
                  "ucp-agent": {
                    "type": "object",
                    "required": ["profile"],
                    "properties": {
                      "profile": {
                        "type": "string",
                        "format": "uri",
                        "description": "Publicly fetchable URI describing your agent."
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "JsonRpcResponse": {
        "type": "object",
        "title": "JsonRpcResponse",
        "description": "JSON-RPC 2.0 response from the MCP endpoint.",
        "required": ["jsonrpc"],
        "properties": {
          "jsonrpc": { "type": "string", "const": "2.0", "description": "Protocol version." },
          "id": { "type": ["string", "integer", "null"], "description": "Correlation id echoed back." },
          "result": { "type": "object", "description": "Method result on success." },
          "error": {
            "type": "object",
            "description": "Error object on failure.",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "integer", "examples": [-32001, -32602], "description": "JSON-RPC error code." },
              "message": { "type": "string", "description": "Error summary." },
              "data": { "type": "object", "description": "Structured detail including a continue_url when a human handoff is needed." }
            }
          }
        }
      },
      "McpManifest": {
        "type": "object",
        "title": "McpManifest",
        "description": "Manifest served at /mcp.json describing this store's MCP server.",
        "required": ["name", "endpoint", "transport"],
        "properties": {
          "name": { "type": "string", "description": "Server name." },
          "description": { "type": "string", "description": "What the server is for." },
          "endpoint": { "type": "string", "format": "uri", "description": "Streamable HTTP endpoint URL." },
          "transport": { "type": "string", "const": "streamable-http", "description": "MCP transport." },
          "protocol_version": { "type": "string", "description": "MCP protocol version." },
          "tools": { "type": "array", "items": { "type": "string" }, "description": "Tool names exposed by the server." }
        }
      }
    }
  }
}