AI assistants & API
MCP server reference
Everything an AI agent can do with Winzos through the MCP server, and how to connect a client to it.
| URL | https://api.winzos.io/mcp |
| Transport | Streamable HTTP, stateless: every request is a POST and carries the key. There are no sessions. |
| Authentication | An API key from Settings → API keys, as Authorization: Bearer wz_live_… or as ?api_key=wz_live_…. No OAuth. |
New to connecting an assistant? Start with Connect an AI assistant.
Tools
A Read only key sees only the tools marked Any. A Full access key sees them all. Every tool returns JSON, both as text and as structured content.
| Tool | What it does | Key |
|---|---|---|
get_account | The account behind the key: store or creator, the store's domain, the link to add Winzos to the store's theme, and what the key may do. Agents call it first. | Any |
list_products | Stores only. Searches the store's active Shopify products by name. Each result says whether it can be a prize: active, with an image, and in stock or never out of stock (a gift card, a product without tracked inventory, or one that keeps selling when out of stock). | Any |
resolve_product | Stores only. Turns a link to a product in the store into the product. | Any |
suggest_contest | Drafts a contest from a product link (the store's, an Amazon page, any product page) or a store product_id: name, prize name and description, value, image and recommended minimums, as validate_contest input. Creates nothing. | Any |
upload_image | Stores an image on the Winzos CDN and returns its URL. Rarely needed, as the contest tools take images directly. | Full access |
validate_contest | Checks a contest without creating it. Returns ready, missing_fields (each with a question to ask), errors and a summary. | Any |
create_contest | Creates the contest and returns it with its share_url and next_steps. | Full access |
update_contest | Changes a contest's details. What can change depends on whether it's scheduled, live or ended; get_contest lists its editable_fields. | Full access |
set_contest_visibility | Makes a contest public (listed on Winzos) or private (unlisted but still running). Public needs the creator's public profile. | Full access |
list_contests | The account's contests with all-time stats. Filters: status, search, is_public, ends_within_hours. | Any |
get_contest | One contest and its stats, all time or for from/to dates, and its editable_fields. | Any |
list_winners | An ended contest's winners in rank order, with claim status. Read only: winners are handled in Winzos Manage. | Any |
get_summary | Contests by status, plus participants, entries, actions and earnings across all contests. | Any |
get_earnings | Lifetime and period earnings, balance, pending payouts and paid out, optionally by contest or by day. | Any |
get_activity | Recent entries and contests starting or ending, newest first. | Any |
Each tool is also a REST endpoint with the same input and output. See the REST API reference.
Creating a contest
The server's instructions walk the agent through this flow, and the tool descriptions repeat it:
- Call
get_account. It says whether the account is a store or a creator, and whether the key can create contests. - Find the prize. When the user has a product link, or wants the contest written for them,
suggest_contestreads the product and drafts the whole input. Otherwise, stores:resolve_productfor a link, orlist_productsto search by name; creators: collect the prize name, description, value and image. - Call
validate_contest. Ask the user for each item inmissing_fields, using its question, and fix anyerrors. - Get the user's go-ahead. Show them the
summary.create_conteststarts the contest, so don't call it without their confirmation. - Call
create_contestwith the same input. Pass itsnext_stepson to the user.
Images go in image_url (a public https link, which Winzos downloads and keeps) or image_base64 (the file itself, or a data: URI). JPEG, PNG, GIF and WebP images up to 10 MB are accepted. Times are ISO 8601 with a time zone. Money is in US cents, and each amount also comes back formatted, for example {"cents": 7500, "formatted": "$75.00"}.
create_contest input
| Field | Who | Notes |
|---|---|---|
ends_at | Everyone | Required. Must be in the future. |
starts_at | Everyone | Optional. Leave it out to start now. |
product_url or product_id | Stores | Required. The link must be to the store's own domain. |
prize_name, prize_description, prize_value_cents | Creators | Required for creators. For stores they default to the product's title, description and price. |
prize_url | Everyone | Optional. An http or https link where people can see or buy the prize (2048 characters at most), shown as "View product" on the contest page and, if the creator turns it on in the Widget Builder, in the widget. Stores default to the product's page in the store; send null to leave it empty. Not the same as product_url, which names a product in the store. Contests return it as prize.url. |
image_url or image_base64 | Creators | Required for creators. Optional for stores, which default to the product image. |
image_urls | Optional | More prize photos, primary (image_url) first: the gallery on the contest page. suggest_contest returns them for a product link. |
name | Everyone | Defaults to "<prize name> Giveaway". suggest_contest writes a catchier one. |
number_of_winners, min_entries_per_user | Everyone | Default 1 and 1. People with fewer entries than min_entries_per_user can't win. |
min_participants, enforce_min_participants | Everyone | A minimum number of entrants, off by default. With enforce_min_participants: true, a contest that fewer than min_participants people enter ends with no draw and no prize, and its page says so before anyone enters. min_participants must then be at least number_of_winners. Honored only while Winzos allows minimums; otherwise the contest is created without one and comes back with min_participants: null. |
participation_prize | Stores | none (default), product_coupon or store_coupon. |
is_public | Everyone | Default true (listed on Winzos) when the creator has a public profile, false when they don't. Listing needs a public profile (a name, and individual or company), added in Winzos Manage → Settings → Public profile; asking for true without one is an is_public error. Use set_contest_visibility to change it later. |
reengagement_nudges | Everyone | Default true. While the contest is live, Winzos emails people who earned entries a reminder to come back and collect more (on some days, not every day), and once more a day before it closes. Everyone can unsubscribe from these emails. Send false to turn them off; you can change it later, even while the contest is live. |
earning_types | Everyone | Default ["surveys", "games", "offers"]. The ways to earn the contest offers: surveys, games, offers, each at most once, at least one. Only these show in the widget and on the contest page. Send fewer only when some kinds should be left out, e.g. ["surveys"] for a surveys-only contest; you can change it later, even while the contest is live (entries already earned stay). |
store_wide | Stores | Default false. With true, the contest's launch button shows on every product page in the store that has the Winzos block, not only on the prize product's page (a gift card giveaway, for example). A product with its own live contest shows that one instead. A store has one live or scheduled store-wide contest at a time: while one exists this is a store_wide error, and the user ends it early (or archives it, if it hasn't started) in Winzos Manage. Can't be changed after creation. |
launcher_label | Stores | Store-wide contests only. The launch button's text, up to 60 characters, in place of the label set in the Widget Builder. Leave it out to use the Widget Builder's label. |
Editing a contest
update_contest takes the contest id (a UUID, as list_contests and get_contest return it) and only the fields to change: name, prize_name, prize_description, prize_value_cents, prize_url (null removes it), image_url or image_base64, image_urls (replaces the photo gallery), number_of_winners, min_participants, enforce_min_participants, min_entries_per_user, participation_prize, is_public, reengagement_nudges, earning_types and, for a store-wide contest, launcher_label (null goes back to the Widget Builder's label). Which of those are allowed depends on the contest's state, and get_contest returns them as editable_fields:
- Scheduled: all of them.
- Live:
name,prize_description,prize_url, the image,is_public,reengagement_nudges,earning_typesand a store-wide contest'slauncher_label. - Ended: none (
CONFLICT).
The start and end times, the product and store_wide never change. Sending starts_at, ends_at, product_url, product_id or store_wide is refused with a message saying so. Get the user's OK before calling it.
Not available here
Winner actions (notifying winners, fulfilling prizes, sending coupons), ending a contest early and withdrawals are done in Winzos Manage on purpose. list_winners is read only.
Errors
A failed call comes back as a tool result with isError: true. Its text is JSON with a code, a message written so it can be passed on to the user, and details when there are field-level problems:
| Code | Status | Meaning |
|---|---|---|
INVALID_API_KEY | 401 | The key is missing, mistyped or revoked. |
INSUFFICIENT_SCOPE | 403 | A Read only key tried to create or change something. |
NOT_FOUND | 404 | No such contest on this account, or no such endpoint. |
PRODUCT_NOT_FOUND | 404 | The product link didn't match a product in the store. |
CONFLICT | 409 | For example, the product already has a live or scheduled contest, or the store already has a store-wide one. |
UNPROCESSABLE_ENTITY | 422 | The input is invalid. data.errors lists each field and the problem. For create, data.missing_fields lists what's missing. |
IMAGE_FETCH_FAILED | 422 | The image link couldn't be downloaded. It must be a public https link. |
IMAGE_INVALID | 422 | The file isn't a JPEG, PNG, GIF or WebP image, or it's over 10 MB. |
SITE_FETCH_FAILED, NO_PRODUCT, NOT_SUITABLE | 422 | suggest_contest couldn't read the page, found no product on it, or found one that can't be a prize. The message says what to try. |
TOO_MANY_REQUESTS | 429 | The key passed its rate limit. data.retry_after_seconds says when to retry. |
Rate limits
Each key can make 60 reads and 10 changes a minute. Over that, calls fail with TOO_MANY_REQUESTS until the minute is up.
Troubleshooting
- The assistant says it can't connect. Check that the URL is exactly
https://api.winzos.io/mcpand that the key wasn't revoked. A typo in the key givesINVALID_API_KEY. - It can read but won't create contests. The key is Read only. Create a Full access key.
- An image won't load. The link must be public, start with
https://and open the image itself, not a page showing it. - An edit is refused with
CONFLICT. The contest is live or ended and that field is frozen.details.editable_fieldssays what can still change. - A store product is refused. It must be active in Shopify, have an image, be in stock or never run out (gift cards, untracked inventory, or set to keep selling when out of stock), and not already have a live or scheduled contest.