The wishlist API
agents already know how to call.
Gish is the first wishlist on the Model Context Protocol. The MCP server is live at mcp.gishme.com; the REST API is live at api.gishme.com. OAuth scopes, 33 outbound webhook events delivered with HMAC-SHA256 signatures, llms.txt v2, PotentialAction schemas on every wish, and a one-line Save-to-Gish JS SDK for retailers. Built so an agent can save, search, contribute, and capture without scraping.
Built for the agent layer.
Every wish on Gish is a structured action an agent can take, not a page it has to scrape.
Most commerce on the web was built for humans clicking buttons. The agent layer that’s now arriving — Claude in Chrome, ChatGPT actions, Cursor, OpenInterpreter, MCP-aware desktop apps — needs something different: a structured, callable surface where every meaningful object has a verb attached. Save this. List my wishes. Contribute to this one. Look up this URL. Capture this product. We built Gish that way from the start.
The Model Context Protocol is the substrate. mcp.gishme.com is a publicly-discoverable MCP server. Any Claude Desktop, Cursor, or compatible client can attach it in seconds, then call gish_save_wish, gish_list_wishes, gish_search, gish_contribute, and gish_capture_url with structured arguments. No browser automation. No DOM scraping. No screen pixels.
Five tools at mcp.gishme.com.
These are the verbs an agent has on Gish today. They cover create, read, search, contribute, and capture.
Save a wish to the authenticated user’s list. Accepts URL, title, image, variant, occasion, deadline, budget. Returns the wish id and canonical URL. The most-called tool in production.
List wishes for the authenticated user or for a public profile. Filter by occasion, status, owner. Pagination via cursor. Useful when an agent is preparing a gift-shortlist or a summary.
Search the public explore index. Returns wishes the user has permission to see. The agent can query by SKU, brand, category, or natural-language intent (“running shoes for a marathon”).
Place a contribution on a wish — full purchase, partial pledge, or group-buy split. Requires agent.write:pledges scope and a user-confirmation step at the wallet boundary.
Take any product URL and resolve it to a structured wish payload — brand, title, price, image, variant. Useful when the agent encountered a URL in conversation and wants to convert it.
Read a single wish by id or canonical URL. Returns the full structured object including occasion, budget, deadline, contributions to date, and PotentialAction links.
Wire it up in under a minute.
Claude Desktop, Cursor, ChatGPT custom GPT — the connection pattern is the same shape, with platform-specific config.
Claude Desktop
Add the Gish MCP server to claude_desktop_config.json. The config block:
Restart Claude. The Gish tools appear in the tool-picker. The first call triggers the OAuth flow; the user grants scopes; subsequent calls are silent.
Cursor
Cursor reads the same mcpServers shape in ~/.cursor/mcp.json. Same block, same flow.
ChatGPT custom GPT
For platforms that don’t speak MCP natively, point a custom GPT at the REST OpenAPI spec at api.gishme.com/openapi.json. ChatGPT’s GPT builder ingests it and exposes the same verbs as actions. OAuth is configured in the GPT’s authentication panel.
Same verbs, HTTP shape.
For runtimes that aren’t MCP-aware: a versioned REST API at api.gishme.com, OAuth 2.1 with PKCE, OpenAPI 3.1 spec, idempotency keys on all writes.
OAuth scopes
agent.read:wishes— read the user’s wishes, profile, contributions to dateagent.write:wishes— create, edit, archive wishes on the user’s behalfagent.write:pledges— place contributions or group-buy pledges (requires wallet confirmation)agent.read:contributions— read contribution history and receiptsagent.write:capture— call capture_url and import structured product dataagent.read:search— query the public explore indexpartner.write:catalog— for retailer partners syncing product feeds (gated)
Scopes are user-grantable individually; the OAuth consent screen shows the exact verbs the agent is asking for, with plain-English summaries.
Unified scanner — /v1/scanner/resolve
One endpoint, three code shapes: UPC/EAN barcodes resolve to a product and land as a wish; TIC-prefixed UIDs verify product authenticity via The Ideal Code platform; Gish QR codes resolve to a wishlist or single wish. The client posts the raw decoded string; the server disambiguates by prefix and shape.
Free for all tiers. Scope: agent.write:capture. The Gish QR path is TIC-backed for unified scan analytics — the user-facing behavior (open the wishlist) is unchanged. See the TIC note below.
33 events for closed-loop flows.
Subscribe at the application or per-user level. Every delivery is HMAC-SHA256 signed with a timestamp prefix (replay-protected), idempotent via a stable delivery id, and retried with exponential backoff at 1m, 5m, 30m, 1h, 6h, then 24h x3 (8 attempts, ~3 days). Deliveries that exhaust the schedule land in the dead-letter queue, replayable from the developer console.
Wish lifecycle
wish.created, wish.updated, wish.deleted, wish.variants_confirmed, wish.price_dropped
Wishlist lifecycle
wishlist.created, wishlist.shared, wishlist.member_added, wishlist.archived
Group buy
group_buy.created, pledge.received, goal.funded, goal.expired, group_buy.completed, thank_you_added
Contribution
contribution.intent_started, contribution.completed, contribution.refunded, contribution.failed, contribution.disputed
Treasury
treasury.created, treasury.deposit_made, treasury.deploy_proposed, treasury.deploy_executed, treasury.deploy_rejected
Booking
booking.queued, booking.assigned_to_ops, booking.confirmed, booking.refunded
User
user.created, user.deleted, user.connect_account_verified, subscription.tier_changed
Subscribe
Headers on every delivery
Signature verification — Node
Signature verification — Python
Signature verification — Ruby
Event reference
Every event payload follows the same envelope:
wish.created
A wish has been saved. Fires from POST /v1/wishes and the Save-to-Gish SDK retailer flow.
wish.updated
Wish metadata changed (title, description, price, visibility, variants).
wish.deleted
wish.variants_confirmed
wish.price_dropped
Smart Savings (Sprint 22A) detected a price drop below the 30-day low. significant: true when delta > 15%.
wishlist.created
wishlist.shared
Fires when a wishlist's privacy flips to public/link-only OR a new invite is sent.
wishlist.member_added
wishlist.archived
group_buy.created
pledge.received
A contribution intent was started — money is authorized but not yet captured.
goal.funded
Aggregate captured-contribution total reached the group buy goal.
group_buy.completed
goal.expired
Group buy deadline elapsed before goal was met. (Emitted by the group-expiry cron.)
thank_you_added
A wisher added a thank-you message to a captured contribution.
contribution.intent_started
contribution.completed
Stripe captured the authorized payment intent. Money is now in the platform account awaiting payout.
contribution.refunded
contribution.failed
contribution.disputed
Stripe issued a chargeback notice. Surfaces in the fraud queue.
treasury.created
treasury.deposit_made
treasury.deploy_proposed
A founder initiated a deploy that requires a quorum vote (treasury has ≥ 2 active members).
treasury.deploy_executed
treasury.deploy_rejected
booking.queued
booking.assigned_to_ops
booking.confirmed
Two-person rule satisfied (or amount < $1k); vendor PNR locked.
booking.refunded
user.created
user.deleted
GDPR/CCPA hard-delete completed by the data-rights worker. Payload carries no PII.
user.connect_account_verified
Stripe Connect account is payouts-enabled. The user can now receive money.
subscription.tier_changed
Payloads carry opaque IDs only — no email addresses, full names, payment instruments, or other PII. Cross-reference on your side using the IDs and the authenticated read APIs. Signing secrets are rotated on demand from the developer console or via PATCH /v1/webhooks/:id. Per-webhook rate limit: 100 events/min/subscription.
Sane limits, elevation on request.
Most agents never touch the ceiling. If yours does, we’ll talk.
| Tier | Req / min | Concurrency | Burst | Identification |
|---|---|---|---|---|
| Anonymous | 30 | 4 | 60 / min | IP + UA fingerprint |
| User token | 600 | 16 | 900 / min | OAuth user token |
| Agent service | 300 | 32 | 500 / min | Agent client credentials |
| Partner / retailer | 2,000 | 64 | 3,500 / min | Signed JWT, partner scope |
| Elevated | custom | custom | custom | Negotiated SLA |
Limit responses include X-RateLimit-Reset and Retry-After. Hit a ceiling repeatedly and the developer console surfaces a self-serve elevation request. Bulk-ingest retailer partners get a separate lane with idempotent batch endpoints up to 500 wishes per call.
llms.txt v2 + PotentialAction everywhere.
Every wish surface is annotated so an agent that hasn’t even authenticated can still understand what actions are possible.
Gish ships an llms.txt v2 manifest at the root domain that lists the public surfaces, the canonical entrypoints, and the agent verbs available against each. Every wish page carries schema.org PotentialAction blocks: SaveAction, BuyAction, ReserveAction, DonateAction. The MCP tool surface and the JSON-LD on the page describe the same verbs, by design. An agent that reads either ends up at the same conclusion about what it can do.
One line for retailers.
Drop the script tag, get a Save-to-Gish button on every product page, with SKU-level capture.
The SDK reads structured-data already on the page (microdata, JSON-LD, Open Graph) and falls back to the data-attributes you provide. A Save-to-Gish button renders adjacent to the retailer’s own “Add to wishlist” control. Click captures the SKU and variant exactly — no scraping, no guesswork. Attribution and affiliate tracking work out of the box.
For platforms, retailers, and agent builders.
If you’re building something that needs structured wishlist intent, we’d like to talk.
Agent platform partners
You’re building a general-purpose agent and you want commerce verbs. We expose Gish as a first-class MCP server, give you elevated rate limits, and co-document the integration. No fee.
Retailer partners
You operate a commerce surface and you want a one-tap Save-to-Gish button with SKU-level fidelity. We tune the SDK to your DOM, wire affiliate tracking, and co-publish on the retailers page.
Editorial & AI tooling
You build editorial tools, gift-guide generators, or shopping assistants. We expose the public explore search through a dedicated read tier so your product can recommend real wishes, not synthetic ones.
What changes when wishes are callable.
The commerce stack agents have today is a brittle assembly of headless browsers, brittle DOM selectors, and PDF receipts. Gish is the alternative shape.
An agent acting on a user’s behalf in 2026 needs three things from a commerce surface: a clean way to read what the user wants, a clean way to mutate it without screen-scraping, and a clean way to settle money with the user’s explicit consent at the moment it’s spent. Every commerce platform built before MCP gets one of those right at most, and usually achieves it by accident through a partner API that wasn’t designed for general agent access. We started from the opposite end.
Every wish on Gish is a first-class addressable object with a stable canonical URL, a structured payload, and a signed PotentialAction surface. Every state-changing call accepts an idempotency key so agents that retry on transient failure don’t accidentally double-charge or duplicate wishes. Every wallet action requires a user-confirmation step at the wallet boundary — the agent can propose a contribution, but only the user’s authenticated session can confirm spend above a per-scope ceiling. That boundary is non-negotiable, and we publish the ceiling explicitly so agent authors can design around it.
The result is the closest thing to a transactional commerce primitive that an agent can call without being a security incident waiting to happen. Saving a wish on a user’s behalf is safe. Listing contributions is safe. Even capturing a URL into a structured wish is safe, because the destination is an opinionated object inside the user’s account, not a free-form web request that could go anywhere. We’ve traded surface-area for safety in places that matter, and we’re explicit about it.
- Idempotency keys are required on every write. Retries are first-class.
- Wallet operations require user confirmation above a per-scope ceiling. Agents propose; users confirm.
- Every object has a canonical URL that resolves to JSON-LD with PotentialAction blocks. Agents that haven’t authenticated can still understand the surface.
- OAuth scopes are minimal and explicit — the consent screen names exactly what the agent will do, in plain English.
- Webhooks are signed and idempotent with 24h exponential-backoff retries and a published signing-key rotation procedure.
- Versioned API surface at
/v1with a 12-month deprecation policy when we ship breaking changes.
What we don’t ship.
Where the line is, today.
Some of these will move; others won’t. We’d rather say what’s real than promise what isn’t. The MCP server today supports the six tools above; tools for browsing other users’ private wishlists, executing booking flows directly through the agent layer, and managing brand-week campaigns programmatically are roadmap items, not shipped. The REST API covers the full surface; the MCP surface is a curated subset chosen for safety and clarity.
The Save-to-Gish SDK is a one-line embed for product pages; for retailers wanting deeper integration (server-side product feed sync, real-time inventory, affiliate-network handoff) the partner-scope JWT is the right path, not the public SDK. The webhook fleet is comprehensive on wishes, contributions, treasury pools, and fund payouts; events for the editorial layer and the brand-week auction are not exposed yet. Rate limits are sane defaults; if you’re building something that’ll exceed them at launch, talk to us before you do, not after.
If a use case isn’t here, ask. The fastest way to get something added to the public surface is to be the first integration that needs it. We’ve shipped tools in days when the use case was clear and the spec was clean.
Three end-to-end agent flows.
What a real agent integration looks like, top to bottom.
Flow one: gift-shortlist generation. A user asks their assistant for ten gift ideas for their sister’s thirtieth birthday on the 14th. The agent calls gish_list_wishes against the sister’s public profile, retrieves the wishes already there, then calls gish_search against the public explore index for adjacent items. It returns a shortlist annotated with deadlines, budget hints, and whether each item is already on her list. The user picks one; the agent calls gish_save_wish on its own user’s account with the gift-tag, opens a contribution flow, and hands off to the user’s wallet for confirmation. End-to-end, four MCP calls and one wallet confirmation.
Flow two: URL capture from a chat thread. A user pastes a product URL into a chat and says “remind me about this for the holidays.” The agent calls gish_capture_url with the URL and gets back a structured wish payload (brand, title, price, image, variant). It calls gish_save_wish with occasion: "holiday" and the user’s default holiday window. Total round-trip: two calls, zero scraping. The agent never touched the destination site’s DOM; Gish’s server-side resolver did the work.
Flow three: retailer-driven save. A retailer has the one-line Save-to-Gish SDK on their product detail page. A logged-in Gish user clicks the button. The SDK posts the SKU and variant directly to the API with a partner-scoped JWT and the user’s session token. The wish appears on the user’s list with affiliate attribution wired up, and a wish.created webhook fires to the retailer’s endpoint for their own analytics. End-to-end: one click, two server-side calls, zero scraping.
A common pattern across all three is that the agent never holds long-lived credentials beyond its OAuth refresh token, and every wallet-touching operation routes through a user-visible confirmation step. We considered shipping a higher-trust agent tier that would let an agent settle small contributions silently, and concluded the asymmetry of harm outweighed the convenience: the worst-case bug in an agent that can silently move money is much worse than the worst-case bug in an agent that has to ask. That tradeoff is conservative on purpose and we don’t expect it to relax soon.
All three flows are documented as full code samples in the developer console. They’re live; they’re what we test against; they’re the canonical examples we point new integrations at. If you have a fourth flow you want supported, the contact form on this page reaches the API team directly. Programmatic access to ad inventory is a separate auth path — see the advertisers page for that surface.
Note · Gish QR codes are powered by The Ideal Code (TIC) platform for unified product authentication and scan analytics. The UX is unchanged; the TIC backing gives Gish, retailer partners, and brand-week advertisers a single source of truth for scan events across UPC, TIC, and Gish QR shapes.