{
  "openapi": "3.1.0",
  "info": {
    "title": "Modern Mood Storefront API",
    "version": "2026-09-10",
    "summary": "Read-only storefront API and agent-discovery surface of the Modern Mood Shopify store.",
    "description": "Machine-readable description of the public surface of https://www.modernmood.com.br.\n\nTwo access tiers exist:\n\n1. **Read-only storefront (this document)** - no authentication, no API key, no OAuth token. Typed JSON endpoints for catalogue, search and site discovery.\n2. **UCP commerce** - cart, checkout and order operations, exposed as Model Context Protocol tools at `POST /api/ucp/mcp` (JSON-RPC 2.0). Discovery document: `GET /.well-known/ucp`. Those operations are intentionally not modelled as REST paths here because they are not REST: they are MCP tools discovered at runtime with `tools/list`, and each call carries a `meta.ucp-agent.profile` argument identifying the agent. See `x-ucp-mcp`.\n\nScope vocabulary for both tiers is declared in `x-permission-scopes` and repeated per operation in `x-scopes`, so an agent can request least-privilege access without reading prose.\n\nPrices are integers in the currency's minor units together with an ISO 4217 code, or decimal strings on the legacy REST JSON endpoints. Payments are never completed by an agent without contemporaneous buyer approval.",
    "contact": {
      "name": "Modern Mood",
      "url": "https://www.modernmood.com.br/pages/contact"
    },
    "license": {
      "name": "Storefront data is provided for shopping and agent use; see the store Terms of Service.",
      "url": "https://www.modernmood.com.br/policies/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://www.modernmood.com.br",
      "description": "Production storefront (Brazil, pt-BR, BRL)"
    }
  ],
  "tags": [
    {
      "name": "catalog",
      "description": "Products, variants and collections."
    },
    {
      "name": "search",
      "description": "Free-text product search."
    },
    {
      "name": "discovery",
      "description": "Agent instructions and machine-readable indexes."
    },
    {
      "name": "commerce",
      "description": "Cart, checkout and order operations over UCP/MCP."
    }
  ],
  "security": [],
  "x-permission-scopes": {
    "storefront.catalog.read": "Read products, variants, prices and availability.",
    "storefront.search.read": "Run free-text product searches.",
    "storefront.sitemap.read": "Enumerate canonical URLs.",
    "storefront.agent_docs.read": "Read agent instructions and discovery metadata.",
    "ucp.catalog.read": "Search and look up catalogue entries over MCP.",
    "ucp.cart.read": "Read a cart over MCP.",
    "ucp.cart.write": "Create and mutate a cart over MCP.",
    "ucp.checkout.write": "Create and progress a checkout over MCP.",
    "ucp.checkout.complete": "Complete a checkout over MCP. Requires contemporaneous buyer approval.",
    "ucp.order.read": "Read an order the buyer owns over MCP."
  },
  "x-ucp-mcp": {
    "discovery": "https://www.modernmood.com.br/.well-known/ucp",
    "endpoint": "https://www.modernmood.com.br/api/ucp/mcp",
    "protocol": "jsonrpc-2.0",
    "transport": "mcp",
    "versions": [
      "2026-08-25",
      "2026-04-08",
      "2026-01-23"
    ],
    "tools": {
      "catalog": [
        "search_catalog",
        "lookup_catalog",
        "get_product"
      ],
      "cart": [
        "create_cart",
        "get_cart",
        "update_cart",
        "cancel_cart"
      ],
      "checkout": [
        "create_checkout",
        "get_checkout",
        "update_checkout",
        "complete_checkout",
        "cancel_checkout"
      ],
      "order": [
        "get_order"
      ]
    },
    "errorSchema": {
      "type": "object",
      "required": [
        "jsonrpc",
        "error"
      ],
      "properties": {
        "jsonrpc": {
          "const": "2.0"
        },
        "id": {
          "type": [
            "integer",
            "string",
            "null"
          ]
        },
        "error": {
          "type": "object",
          "required": [
            "code",
            "message"
          ],
          "properties": {
            "code": {
              "type": "integer",
              "description": "JSON-RPC class. -32602 invalid params, -32001 protocol or discovery failure.",
              "examples": [
                -32602,
                -32001
              ]
            },
            "message": {
              "type": "string"
            },
            "data": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "description": "Stable machine-readable reason. Branch on this, not on message text.",
                  "examples": [
                    "invalid_profile_url",
                    "profile_unreachable"
                  ]
                },
                "content": {
                  "type": "string",
                  "description": "Human-readable detail, safe to log."
                },
                "continue_url": {
                  "type": "string",
                  "format": "uri",
                  "description": "Where to resume; a storefront URL means the user must continue in the browser."
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/products/{handle}.json": {
      "get": {
        "operationId": "getProductJson",
        "summary": "Get one product with its variants",
        "description": "Returns a single product by handle, including variants, prices and stock state. Requires no authentication.",
        "tags": [
          "catalog"
        ],
        "x-scopes": [
          "storefront.catalog.read"
        ],
        "security": [],
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "description": "Product handle, e.g. `cinzeiro-duck-resina-decorativo`.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$",
              "maxLength": 255
            },
            "example": "cinzeiro-duck-resina-decorativo"
          }
        ],
        "responses": {
          "200": {
            "description": "The product.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "product"
                  ],
                  "properties": {
                    "product": {
                      "$ref": "#/components/schemas/Product"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "No product with that handle. The storefront returns HTTP 404 for unknown handles.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "null"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/collections/{handle}/products.json": {
      "get": {
        "operationId": "listCollectionProductsJson",
        "summary": "List the products of a collection",
        "description": "Returns the products of a collection in storefront order. Use `handle=all` for the full catalogue.",
        "tags": [
          "catalog"
        ],
        "x-scopes": [
          "storefront.catalog.read"
        ],
        "security": [],
        "parameters": [
          {
            "name": "handle",
            "in": "path",
            "required": true,
            "description": "Collection handle, or `all` for every published product.",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$"
            },
            "example": "all"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of products to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 250,
              "default": 50
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "1-based page number.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The collection's products.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "products"
                  ],
                  "properties": {
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown collection handle."
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/search/suggest.json": {
      "get": {
        "operationId": "searchProductSuggestions",
        "summary": "Suggest products for a query",
        "description": "Typed-prediction endpoint used by the storefront search box. Cheaper than rendering the search page and safe to call per keystroke with debouncing.",
        "tags": [
          "search"
        ],
        "x-scopes": [
          "storefront.search.read"
        ],
        "security": [],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search term.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "example": "cinzeiro"
          },
          {
            "name": "resources[type]",
            "in": "query",
            "required": false,
            "description": "Resource types to search. Comma-separated subset of `product,collection,page,article`.",
            "schema": {
              "type": "string",
              "default": "product"
            },
            "example": "product"
          },
          {
            "name": "resources[limit]",
            "in": "query",
            "required": false,
            "description": "Maximum suggestions per resource type.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 10
            }
          },
          {
            "name": "section_id",
            "in": "query",
            "required": false,
            "description": "Theme section id used for server-side section rendering. Not required for JSON use.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Suggestion payload.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "resources"
                  ],
                  "properties": {
                    "resources": {
                      "type": "object",
                      "properties": {
                        "results": {
                          "type": "object",
                          "properties": {
                            "products": {
                              "type": "array",
                              "items": {
                                "$ref": "#/components/schemas/ProductSuggestion"
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/sitemap.xml": {
      "get": {
        "operationId": "getSitemapIndex",
        "summary": "Get the sitemap index",
        "description": "XML sitemap index. Follow the child sitemaps for products, collections, pages, blogs and agentic discovery.",
        "tags": [
          "discovery"
        ],
        "x-scopes": [
          "storefront.sitemap.read"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Sitemap index.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/agents.md": {
      "get": {
        "operationId": "getAgentInstructions",
        "summary": "Get agent instructions",
        "description": "Canonical, agent-facing description of the store: when to use it, scoped permissions, UCP/MCP endpoints, error format, etiquette and trust anchors. Served as `text/markdown`. `/llms.txt` and `/llms-full.txt` mirror this document.",
        "tags": [
          "discovery"
        ],
        "x-scopes": [
          "storefront.agent_docs.read"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Agent instructions in markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/ucp": {
      "get": {
        "operationId": "getUcpDiscovery",
        "summary": "Get the UCP discovery document",
        "description": "Universal Commerce Protocol merchant profile: supported versions, service endpoints, capabilities, payment handlers and the MCP transport endpoint.",
        "tags": [
          "discovery",
          "commerce"
        ],
        "x-scopes": [
          "ucp.catalog.read"
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "UCP merchant profile.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ucp"
                  ],
                  "properties": {
                    "ucp": {
                      "type": "object",
                      "properties": {
                        "version": {
                          "type": "string"
                        },
                        "supported_versions": {
                          "type": "object"
                        },
                        "services": {
                          "type": "object"
                        },
                        "capabilities": {
                          "type": "object"
                        },
                        "payment_handlers": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "UCP is not enabled for this store."
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "TooManyRequests": {
        "description": "Rate limited. Back off with exponential delay and jitter, then retry.",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying.",
            "schema": {
              "type": "integer"
            }
          }
        }
      }
    },
    "schemas": {
      "Money": {
        "type": "object",
        "description": "Decimal price string plus currency code, as returned by the storefront JSON endpoints.",
        "properties": {
          "amount": {
            "type": "string",
            "pattern": "^[0-9]+\\.[0-9]{2}$",
            "example": "249.90"
          },
          "currency_code": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "example": "BRL"
          }
        }
      },
      "Variant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string",
            "example": "Default Title"
          },
          "price": {
            "type": "string",
            "example": "249.90"
          },
          "compare_at_price": {
            "type": [
              "string",
              "null"
            ]
          },
          "available": {
            "type": "boolean"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "requires_shipping": {
            "type": "boolean"
          },
          "taxable": {
            "type": "boolean"
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "title",
          "handle",
          "variants"
        ],
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string",
            "example": "Cinzeiro Duck"
          },
          "handle": {
            "type": "string",
            "example": "cinzeiro-duck-resina-decorativo"
          },
          "body_html": {
            "type": "string",
            "description": "Description as HTML."
          },
          "vendor": {
            "type": "string",
            "example": "Modern Mood"
          },
          "product_type": {
            "type": "string",
            "example": "Decoração"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "published_at": {
            "type": "string",
            "format": "date-time"
          },
          "variants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Variant"
            }
          },
          "images": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "src": {
                  "type": "string",
                  "format": "uri"
                },
                "alt": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "width": {
                  "type": "integer"
                },
                "height": {
                  "type": "integer"
                }
              }
            }
          },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "ProductSuggestion": {
        "type": "object",
        "description": "Compact product shape returned by the suggest endpoint.",
        "properties": {
          "id": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "handle": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Storefront-relative URL."
          },
          "available": {
            "type": "boolean"
          },
          "price": {
            "type": "string"
          },
          "image": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "body": {
            "type": "string",
            "description": "Truncated, HTML-stripped description."
          }
        }
      }
    }
  }
}