AI assistants & API
Connect Winzos to your AI assistant
Create contests and check your results by asking your AI assistant, in plain words. It takes an API key and a couple of minutes to set up.
Once Winzos is connected, you can ask your assistant things like:
- "Create a contest using the attached image. The prize is a signed poster worth $40, and it ends next Friday."
- "Create a Winzos contest for this product: https://yourstore.com/products/blue-hoodie"
- "How many participants were there in my Blue Hoodie Giveaway?"
- "How many contests are live right now?"
- "How much money have I made across all my contests?"
- "Which contests are ending soon?"
The assistant works through Winzos's MCP server. MCP is the standard way AI assistants connect to other services. It acts only for your account, with an API key you create and can revoke at any time.
1. Create an API key
- Open your API keys. In Winzos Manage, go to Settings → API keys.
- Click Create API key. Give it a name you'll recognize later, like "Claude on my laptop".
- Choose the access. Read only lets the assistant look at your contests, stats and earnings. Full access also lets it create contests and make them public or private.
- Click Create key and copy what you need. You'll see the key, a ready-made MCP URL with the key in it, and a config snippet. Use whichever your assistant asks for.
2. Add Winzos to your assistant
Every assistant has a place to add a custom connector or MCP server. The menu names change from time to time, so if a step below doesn't match what you see, look for those words in the assistant's settings. Some assistants only offer custom connectors on certain plans.
Claude (claude.ai and the desktop app)
- Open the connector settings. Go to Settings → Connectors and choose to add a custom connector.
- Paste the MCP URL with your key. It looks like
https://api.winzos.io/mcp?api_key=wz_live_…. Name it "Winzos". - Turn it on in a chat. Then ask away.
ChatGPT
ChatGPT adds custom MCP servers as connectors, usually after you switch on developer mode in its settings. Paste the MCP URL with your key as the server URL, with no extra authentication.
Cursor and other code editors
Editors like Cursor and Windsurf read MCP servers from a config file. Paste the config snippet from Winzos Manage. It sends your key as a header instead of in the URL:
{
"mcpServers": {
"winzos": {
"url": "https://api.winzos.io/mcp",
"headers": { "Authorization": "Bearer wz_live_your_key" }
}
}
}Claude Code (terminal)
claude mcp add --transport http winzos https://api.winzos.io/mcp \
--header "Authorization: Bearer wz_live_your_key"How creating a contest works
Ask for a contest in your own words. The assistant then:
- Checks your account type. Stores give away one of their Shopify products. Creators describe their own prize.
- Collects what's missing. A store needs a product: paste its link, or name it and pick from the matches. A creator needs the prize's name, a short description, its value and an image. Both need an end date.
- Shows you a summary. Nothing is created until you say yes.
- Creates the contest and tells you what's next. Creators get the link to share. Stores get told where the contest appears, plus the link to add Winzos to their store if they haven't yet.
Contests start straight away unless you give a start time. Unless you say otherwise, they have 1 winner, need 10 participants before a winner is drawn, need 1 entry to qualify and are listed publicly on Winzos. To keep a contest unlisted while you get ready, ask the assistant to make it private, or turn off Make Public in the contest's menu in Winzos Manage. The share link and your store page work either way.
Images
Attach an image to your message or paste a link to one. Winzos keeps its own copy, so the contest doesn't break if the original moves. JPEG, PNG, GIF and WebP images up to 10 MB work. If your assistant can't pass an attachment along, it will ask you for a link instead. Stores can skip this: the product's own image is used unless you give another one.
Asking about results
The assistant can tell you how many contests are live, scheduled or ended; how many people took part and how many entries they earned, for one contest or all of them, over any dates; which contests end soon; who won and whether they've claimed their prize; and how much you've earned, what's ready to withdraw and what's been paid out.
Earnings are always your own share. Participants appear by first name and last initial, never by email.
Changing a contest
Ask for the change, for example "Change the prize description on my hoodie contest" or "Make it 3 winners instead of 1". The assistant tells you what will change and waits for your OK. What can change depends on where the contest is:
- Scheduled: everything except its start and end times and its product.
- Live: only the name, image, prize description, prize link, whether it's public, whether Winzos sends re-engagement nudges and which ways to earn it offers. People have already entered under the contest's terms.
- Ended: nothing.
To change the dates or the product, create a new contest.
Done in Winzos Manage
Some things stay in Winzos Manage, where you can see the whole picture: everything to do with winners (notifying them, sending prizes and coupons, marking prizes as sent), ending a contest early and withdrawing earnings. The assistant can tell you who won and whether they've claimed, then point you to the dashboard. A Read only key can't create or change anything.
Revoke a key
In Settings → API keys, click Revoke next to the key. Anything using it stops working straight away. Each key also shows when it was last used.
What's next?
Building your own integration? See the MCP server reference and the REST API reference. Questions? Email help@winzos.io.