The Yanni API

Mint a token (below), then ask what it is allowed to do:

export YANNI_TOKEN=ysk_live_...

curl -H "Authorization: Bearer $YANNI_TOKEN" \
  https://www.yanni.app/api/v1/business

List your inventory, up to 200 items a page:

curl -H "Authorization: Bearer $YANNI_TOKEN" \
  "https://www.yanni.app/api/v1/items?limit=200&status=all"

Every list answers { data, next_cursor, has_more }. Pass next_cursor back as ?cursor= until it is null. Sold items are hidden unless you pass status=all or status=sold.

Tokens are minted in the app under Settings → API tokens, by an owner or admin. Name it after what will use it and tick the scopes it needs.

The secret is shown once.Only a fingerprint of it is stored, so nobody can show it to you again, us included. Lose it and revoke it; revoking takes effect on the token's next request.

A token is bound to one business and inherits the permissions of the person who created it. Demote them and the token is demoted with them; remove them from the business and it stops working. Send it on every request:

Authorization: Bearer ysk_live_...

items:write cannot book revenue. Listing, re-pricing and unlisting are inventory; recording a sale writes money into your books and needs sales:write. Give an agent the narrower scope unless it is genuinely selling for you.

Relative to https://www.yanni.app/api/v1. Parameters and bodies are in the OpenAPI document.

Fields are snake_case, money is integer cents, timestamps are ISO 8601 UTC. Items can be addressed by id or by SKU (YNI-0042). Cost and profit are redacted by the token creator's role, and redaction reads as 0, not as a missing field.

Send an Idempotency-Key on every write. The same key with the same body replays the first response instead of doing it twice, so a retry after a timeout cannot create a second item. Keys are remembered for 24 hours.

curl -X POST https://www.yanni.app/api/v1/items \
  -H "Authorization: Bearer $YANNI_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "title": "Harley single stitch tee", "size": "L", "asking_price_cents": 8500 }'

PATCH changes only the fields you name; null clears one. An unknown field is a 422 naming it, so a typo fails loudly rather than doing nothing.

Yanni is also an MCP server, so Claude, Cursor and other MCP clients can use your inventory as tools without writing any code. It uses the same tokens, scopes, limits and errors as the API above, and every change an agent makes is logged as coming through MCP.

https://www.yanni.app/api/mcp

Claude Code and other clients that connect to a remote server directly:

claude mcp add --transport http yanni https://www.yanni.app/api/mcp \
  --header "Authorization: Bearer ysk_live_..."

Claude Desktop only starts local programs from its config file, so it reaches Yanni through the mcp-remote bridge. The token goes in env, where other programs on the machine cannot read it off the command line, and the bridge is pinned to one version:

{
  "mcpServers": {
    "yanni": {
      "command": "npx",
      "args": ["-y", "mcp-remote@0.14.3", "https://www.yanni.app/api/mcp",
               "--header", "Authorization:${YANNI_AUTH}"],
      "env": { "YANNI_AUTH": "Bearer ysk_live_..." }
    }
  }
}

An agent sees only the tools its token's scopes allow:

Grant the least you can. An agent that adds stock needs items:read and items:write. Only an agent that records sales needs sales:write, and one sale is at most 25 items. Your client asks before update_item, record_listing and mark_soldunless you have told it to always allow them, so don't, for those three. Ending a listing Yanni put on eBay itself takes it down on eBay.

Tool output is data, not instructions.Sale notes and buyer names can be typed by people outside your business. If you build an agent on Yanni, don't let text it reads there tell it what to do.

300 requests per 60 seconds, per token. Past that, every endpoint answers 429 with retry_after_seconds in the body and these headers:

Sleep that long and carry on. A refused request is not processed, so a 429 on a write means it did not happen — retry under the same Idempotency-Key.

The window is fixed, not sliding: it opens on your first request and closes 60 seconds later. Each token has its own budget, and Settings shows how much of it each one has used this minute. Page at limit=200 rather than requesting items one at a time, and poll /sales?since= every few minutes — there are no webhooks.

Every failure has one shape. Branch on code, never on message — the message is for a person reading a log and may be reworded.

{ "error": { "code": "forbidden", "message": "...", "required_scope": "items:write" } }

• No photo upload. Items created through the API arrive with photos: [] and are photographed in the app.
• No DELETE.Agents get prompt-injected, and destructive operations should be bounded by the API's shape rather than a model's judgement. Deleting is done by a person, in the app.
• No webhooks, OAuth or SDKs yet. Poll, use a token, and generate a client from the OpenAPI document.

/v1 is versioned in the path. Fields may be added without notice; nothing is removed or renamed inside v1, so ignore fields you don't recognise.

Stuck, or want something the API doesn't do? Write in.