# Ziffi Commerce API

> One API for cross-brand product discovery, pricing, and commerce over Shopify brands. Search products, read full detail, get live prices and working discount codes, and drive it all from an AI agent over MCP.

Base URL: https://dev.ziffi.xyz
OpenAPI (machine contract): https://dev.ziffi.xyz/openapi.json
MCP server (JSON-RPC 2.0): https://dev.ziffi.xyz/v1/mcp

## Access
Free tier: try it with no signup, one shared rate limit per IP. Sign up for an `X-Ziffi-Key` to use your key's own higher limit and to attribute usage to your app.

## Core endpoints
- GET https://dev.ziffi.xyz/v1/search?q=QUERY&mode=hybrid|semantic|lexical&limit=N (max 40) - top product results
- GET https://dev.ziffi.xyz/v1/products/ID - full product detail (ID is a product_uid `sha:...` or a uuid)
- GET https://dev.ziffi.xyz/v1/products/ID/price - live price and stock
- GET https://dev.ziffi.xyz/v1/recommend?product_id=UUID - related products
- GET https://dev.ziffi.xyz/v1/coupons?brand=SLUG - discount codes validated at the live cart
- POST https://dev.ziffi.xyz/v1/mcp - MCP tools: search_products, get_product, get_price, recommend, suggest, find_coupons

Every response is `{data, provenance, as_of, tier}`; read results from `data`. Money is integer minor units (paise/cents) with a currency. There is no catalogue-enumeration endpoint by design.

## Docs
- [Get started](https://dev.ziffi.xyz/docs/content/get-started.md)
- [Authentication](https://dev.ziffi.xyz/docs/content/authentication.md)
- [The response envelope](https://dev.ziffi.xyz/docs/content/envelope.md)
- [Tiers and freshness](https://dev.ziffi.xyz/docs/content/tiers.md)
- [Identifiers](https://dev.ziffi.xyz/docs/content/identifiers.md)
- [Pagination](https://dev.ziffi.xyz/docs/content/pagination.md)
- [Errors](https://dev.ziffi.xyz/docs/content/errors.md)
- [Rate limits](https://dev.ziffi.xyz/docs/content/rate-limits.md)
- [Search products](https://dev.ziffi.xyz/docs/content/guide-search.md)
- [Get a product](https://dev.ziffi.xyz/docs/content/guide-product.md)
- [Get live price](https://dev.ziffi.xyz/docs/content/guide-price.md)
- [Find working coupons](https://dev.ziffi.xyz/docs/content/guide-coupons.md)
- [Recommend and similar](https://dev.ziffi.xyz/docs/content/guide-recommend.md)
- [Build an AI agent](https://dev.ziffi.xyz/docs/content/guide-agents.md)
- [Hand off to checkout](https://dev.ziffi.xyz/docs/content/guide-checkout.md)
- [API reference](https://dev.ziffi.xyz/docs/content/reference.md)
- [MCP and connectors](https://dev.ziffi.xyz/docs/content/mcp.md)
- [Changelog](https://dev.ziffi.xyz/docs/content/changelog.md)