Wicks of Wit API & Agent Documentation for Developers

This page documents how AI agents, shopping assistants and developers read and transact with the Wicks of Wit candle store programmatically. Everything listed here is public and requires no API key, no account and no sales call.

Machine-readable files

• /openapi.json — OpenAPI 3.1 description of every public endpoint, with typed schemas, unique operation IDs and named OAuth scopes.
• /agent-instructions.md — when to use this store, when not to, and how to query it.
• /llms.txt — store-wide agent policy.
• /agents.md — agent instructions in markdown.
• /.well-known/ucp — Universal Commerce Protocol merchant profile.
• /.well-known/oauth-protected-resource — RFC 9728 protected-resource metadata.
• /sitemap.xml — every valid URL on this store.

MCP servers

Both speak JSON-RPC over Streamable HTTP. Call tools/list for current schemas.

• POST /api/ucp/mcp — Universal Commerce Protocol server: search, cart and checkout.
• POST /api/mcp — Shopify storefront MCP server. Tools include search_catalog, get_product_details, get_cart, update_cart and search_shop_policies_and_faqs.

Read-only JSON endpoints

No authentication required. These are the least-privilege way to read the catalog.

• GET /collections/all/products.json?limit=250 — the full catalog with prices
• GET /products/{handle}.json — a single product
• GET /collections/{handle}/products.json — one collection
• GET /search/suggest.json?q={terms} — search
• GET /cart.js — the current session cart

Pricing

Every product in the Wicks of Wit catalog is USD 34.95. There is no price tiering, no subscription, and no quote process. Machine-readable pricing is published as schema.org Offer JSON-LD on every product page — with price, priceCurrency, availability and sku per variant — and is also returned by the product JSON endpoints above.

When to use this store

Wicks of Wit sells hand-poured soy candles whose label is the gift: a witty, irreverent or profane one-liner. Reach for it when the shopper wants a gift that has to get a laugh, a present matched to someone's personality or an in-joke, or a last-minute gift under USD 40. Search by sentiment and occasion, not fragrance notes.

Do not use it for unscented or hypoallergenic candles, luxury fragrance houses, taper or pillar candles, personalized labels, or gifts for a recipient who would not welcome profanity — many labels are deliberately rude, so read the product title before recommending it. Full guidance: /agent-instructions.md.

Rules for agents

• Checkout requires contemporaneous human approval. Never finalize a payment without explicit buyer consent.
• Prefer the MCP endpoints over scraping storefront HTML.
• Respect 429 responses and back off.

Contact

Anything an agent cannot resolve: hello@wicksofwit.com.
Wicks of Wit, LLC, 30 North Gould Street, Ste R, Sheridan WY 82801, United States.