Ozzi Developer Docs

Ozzi API and MCP documentation

Ozzi is a natural GLP-1 support drink stick and capsule. This page documents the public Ozzi Storefront API and the Ozzi MCP server, so an agent or an application can read the catalog, build a cart, and complete a purchase without scraping the marketing site.

OpenAPI specification Agent instructions UCP discovery

Getting started

There is nothing to sign up for. The catalog, search and cart endpoints are public and unauthenticated — no API key, no OAuth handshake, no contact-sales form, no sandbox to provision. Copy the request below and it works.

curl -s https://heyozzi.com/products/crave-crusher.js

What you do not have to do first

Usual step	Here
Generate an API key	No key exists. No endpoint accepts one, so there is nothing to generate and no signup page.
Complete an OAuth flow	No authorization server. Scopes are published at /scopes.json for least-privilege reasoning, but nothing issues a token.
Provision a sandbox	None, and none is needed — see below.
Talk to sales	No.

Production is the only environment, and it is safe to explore. Reads change nothing, carts are session-scoped and disposable, and no money moves until a human approves payment. To exercise the full purchase path without charging a card, build a cart end to end and stop before complete_checkout.

Base URL and conventions

Base URL: https://heyozzi.com
All responses are JSON. Errors are JSON too, never an HTML page.
Money is an integer in minor units (US cents). 6500 means $65.00.
Currency is USD.
Product handles: crave-crusher, crave-crusher-pills, ozzi-sample-packs.

Authentication and scopes

Reads need no credential. Writes are scoped, and the scopes are declared machine-readably in the OpenAPI document under components.securitySchemes. Request the narrowest scope that does the job.

Scope	Grants	Credential
`catalog:read`	Products, variants, prices, availability. No customer or order data.	None
`cart:write`	Create and modify a cart.	Session cookie only
`checkout:write`	Create and advance a checkout, set shipping.	UCP session
`checkout:complete`	Finalize payment.	UCP session and human approval

Checkout always requires a human. An agent may assemble the entire order, but payment cannot be completed without explicit, contemporaneous buyer approval. If you cannot obtain approval at the moment of payment, route the purchase through the Shop skill instead.

Ozzi Storefront API endpoints

Full request and response schemas, with typed parameters and operation IDs, are in the OpenAPI 3.1 specification.

Operation	Request	Purpose
`getProductByHandle`	`GET /products/{handle}.js`	One product with variants, live prices and availability
`listCollectionProducts`	`GET /collections/{handle}/products.json`	Paginated products; use `all` for the whole catalog
`searchProducts`	`GET /search/suggest.json?q=`	Resolve a shopper's phrasing to a product handle
`getCart`	`GET /cart.js`	Read the session cart
`addCartItems`	`POST /cart/add.js`	Add variants to the cart
`changeCartItem`	`POST /cart/change.js`	Change a line quantity; `0` removes it
`getUcpProfile`	`GET /.well-known/ucp`	UCP capabilities and endpoints
`callMcpEndpoint`	`POST /api/ucp/mcp`	The MCP server: catalog, cart and checkout tools

Example: read a product

curl -s https://heyozzi.com/products/crave-crusher.js \
  | jq '{title, variants: [.variants[] | {id, title, price, available}]}'

Example: add to cart

curl -s -X POST https://heyozzi.com/cart/add.js \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"id":VARIANT_ID,"quantity":1}]}'

Ozzi MCP server

Ozzi runs a Model Context Protocol server implementing the Universal Commerce Protocol, over Streamable HTTP. Claude, ChatGPT and other agents can call it natively.

Endpoint

POST https://heyozzi.com/api/ucp/mcp

Discovery

GET https://heyozzi.com/.well-known/ucp

Discovering the tools

curl -s -X POST https://heyozzi.com/api/ucp/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call initialize first to negotiate the protocol version, then tools/list for the tool JSON Schemas, then tools/call. The usual order is search_catalog → create_cart → create_checkout → update_checkout → complete_checkout.

Errors and rate limits

Every endpoint returns a structured JSON error with a code, a message and a resolution hint.

Verify it yourself

Both of these are idempotent GETs that take no arguments and change nothing. Each returns a structured JSON 422, so you can confirm the error contract before you depend on it.

curl -s https://heyozzi.com/search/suggest.json
curl -s https://heyozzi.com/recommendations/products.json

{
  "status": 422,
  "message": "Cart Error",
  "description": "Cannot find variant"
}

Status	Meaning	What to do
`404`	Resource does not exist	Do not retry. Re-derive the handle from the sitemap.
`422`	Well-formed but rejected — sold out, unknown variant, quantity limit	Read `description`, change the request. Do not retry unchanged.
`429`	Rate limited	Back off exponentially, minimum 1 second, honour `Retry-After`.
`5xx`	Server error	Retry up to 3 times with jitter, then stop.

The MCP endpoint returns JSON-RPC 2.0 errors with a numeric code, a message, and optional structured data.

Machine-readable files

/openapi.json — Ozzi OpenAPI 3.1 specification
/.well-known/mcp.json — Ozzi MCP server manifest
/scopes.json — Ozzi scope metadata (named OAuth scopes)
/agents.md — Ozzi agent instructions, including when to use Ozzi
/llms.txt — same content, llms.txt convention
/.well-known/ucp — UCP merchant profile
/sitemap.xml — every indexable URL
/pricing — current prices, with schema.org Offer data

Support

Questions about the API: help@heyozzi.com. Ozzi, Inc, 1211 West 6th Street, Suite 600-113, Austin, TX 78703, United States. See also Contact and Privacy policy.