Participating in a contest? Visit this resource

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.

URLhttps://api.winzos.io/mcp
TransportStreamable HTTP, stateless: every request is a POST and carries the key. There are no sessions.
AuthenticationAn 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.

Prefer the header when your client supports it. A key in a URL is as secret as the key itself, and URLs are easier to leak through screenshots, logs and shared configs.

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.

ToolWhat it doesKey
get_accountThe 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_productsStores 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_productStores only. Turns a link to a product in the store into the product.Any
suggest_contestDrafts 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_imageStores an image on the Winzos CDN and returns its URL. Rarely needed, as the contest tools take images directly.Full access
validate_contestChecks a contest without creating it. Returns ready, missing_fields (each with a question to ask), errors and a summary.Any
create_contestCreates the contest and returns it with its share_url and next_steps.Full access
update_contestChanges 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_visibilityMakes a contest public (listed on Winzos) or private (unlisted but still running). Public needs the creator's public profile.Full access
list_contestsThe account's contests with all-time stats. Filters: status, search, is_public, ends_within_hours.Any
get_contestOne contest and its stats, all time or for from/to dates, and its editable_fields.Any
list_winnersAn ended contest's winners in rank order, with claim status. Read only: winners are handled in Winzos Manage.Any
get_summaryContests by status, plus participants, entries, actions and earnings across all contests.Any
get_earningsLifetime and period earnings, balance, pending payouts and paid out, optionally by contest or by day.Any
get_activityRecent 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:

  1. Call get_account. It says whether the account is a store or a creator, and whether the key can create contests.
  2. Find the prize. When the user has a product link, or wants the contest written for them, suggest_contest reads the product and drafts the whole input. Otherwise, stores: resolve_product for a link, or list_products to search by name; creators: collect the prize name, description, value and image.
  3. Call validate_contest. Ask the user for each item in missing_fields, using its question, and fix any errors.
  4. Get the user's go-ahead. Show them the summary. create_contest starts the contest, so don't call it without their confirmation.
  5. Call create_contest with the same input. Pass its next_steps on 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

FieldWhoNotes
ends_atEveryoneRequired. Must be in the future.
starts_atEveryoneOptional. Leave it out to start now.
product_url or product_idStoresRequired. The link must be to the store's own domain.
prize_name, prize_description, prize_value_centsCreatorsRequired for creators. For stores they default to the product's title, description and price.
prize_urlEveryoneOptional. 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_base64CreatorsRequired for creators. Optional for stores, which default to the product image.
image_urlsOptionalMore prize photos, primary (image_url) first: the gallery on the contest page. suggest_contest returns them for a product link.
nameEveryoneDefaults to "<prize name> Giveaway". suggest_contest writes a catchier one.
number_of_winners, min_entries_per_userEveryoneDefault 1 and 1. People with fewer entries than min_entries_per_user can't win.
min_participants, enforce_min_participantsEveryoneA 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_prizeStoresnone (default), product_coupon or store_coupon.
is_publicEveryoneDefault 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_nudgesEveryoneDefault 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_typesEveryoneDefault ["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_wideStoresDefault 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_labelStoresStore-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_types and a store-wide contest's launcher_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:

CodeStatusMeaning
INVALID_API_KEY401The key is missing, mistyped or revoked.
INSUFFICIENT_SCOPE403A Read only key tried to create or change something.
NOT_FOUND404No such contest on this account, or no such endpoint.
PRODUCT_NOT_FOUND404The product link didn't match a product in the store.
CONFLICT409For example, the product already has a live or scheduled contest, or the store already has a store-wide one.
UNPROCESSABLE_ENTITY422The input is invalid. data.errors lists each field and the problem. For create, data.missing_fields lists what's missing.
IMAGE_FETCH_FAILED422The image link couldn't be downloaded. It must be a public https link.
IMAGE_INVALID422The file isn't a JPEG, PNG, GIF or WebP image, or it's over 10 MB.
SITE_FETCH_FAILED, NO_PRODUCT, NOT_SUITABLE422suggest_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_REQUESTS429The 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/mcp and that the key wasn't revoked. A typo in the key gives INVALID_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_fields says 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.