AI assistants & API
REST API reference
Create contests and read their reports from your own code, with the same API key the MCP server uses.
| Base URL | https://api.winzos.io/v1 |
| OpenAPI | https://api.winzos.io/v1/openapi.json (OpenAPI 3.1, no key needed) |
| Format | JSON in and out. Times are ISO 8601 in UTC. Date filters are YYYY-MM-DD and include both ends. |
The REST API and the MCP server are the same operations. Each endpoint below names its MCP tool.
Authentication
Create a key in Settings → API keys in Winzos Manage (see Create an API key). Send it as a Bearer token:
curl https://api.winzos.io/v1/me \
-H "Authorization: Bearer wz_live_your_key"Or, for tools that can't set headers, as the api_key query parameter: https://api.winzos.io/v1/me?api_key=wz_live_your_key. If you send both, they must be the same key.
Read only keys can call every endpoint that only reads. Creating a contest, changing its visibility and uploading images need a Full access key.
Conventions
- Money is an object in US cents with a formatted copy:
{"cents": 7500, "formatted": "$75.00"}. Earnings are always your share. - Lists take
page(from 1) andlimit(up to 100) and returnpaginationwithtotal_countandtotal_pages. - Contests include
share_url, the page participants open to enter. - Contest ids are UUIDs, like
3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c. Send a contest'sidback as{id}orcontest_id. Numeric ids from before November 2026 still work. - Participants appear by first name and last initial only.
Errors and limits
Errors come back with the matching HTTP status and a JSON body:
{
"success": false,
"message": "ends_at: must be in the future",
"code": "UNPROCESSABLE_ENTITY",
"statusCode": 422,
"data": { "errors": [{ "field": "ends_at", "message": "must be in the future" }] }
}| 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. |
PUBLIC_PROFILE_REQUIRED | 422 | Making a contest public needs the creator's public profile (a name, and individual or company). They add it in Winzos Manage → Settings → Public profile. Making a contest private always works. |
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. |
TOO_MANY_REQUESTS | 429 | The key passed its rate limit. data.retry_after_seconds says when to retry. |
Each key can make 60 reads and 10 changes a minute.
Account
GET /v1/me
MCP tool: get_account. The account behind the key: type is store or creator. For stores, theme_setup_url opens the Shopify theme editor with the Winzos block ready to add.
Contests
GET /v1/contests
MCP tool: list_contests. Your contests, newest first, each with all-time stats: participants, entries, actions_completed and earnings.
| Parameter | Description |
|---|---|
status | scheduled, live or ended. |
search | Match contest or prize names containing this text. |
is_public | true or false. |
ends_within_hours | Only contests ending between now and this many hours from now. Pair it with status=live&sort=ends_at&order=asc for "ending soon". |
sort, order | created_at (default), starts_at, ends_at or name; asc or desc (default). |
page, limit | Pagination. Default 20 a page. |
curl "https://api.winzos.io/v1/contests?status=live&ends_within_hours=72&sort=ends_at&order=asc" \
-H "Authorization: Bearer wz_live_your_key"GET /v1/contests/{id}
MCP tool: get_contest. One contest and its stats. Stats are all-time unless from and/or to narrow them.
| Parameter | Description |
|---|---|
from, to | Optional dates, YYYY-MM-DD, UTC. |
GET /v1/contests/{id}/winners
MCP tool: list_winners. Winners in rank order with status (pending, notified, claimed, fulfilled or forfeited) and claim_deadline. Read only: notifying winners and fulfilling prizes are done in Winzos Manage.
Creating and editing contests
Check a contest with validate_contest, show its summary to whoever it's for, then send the same body to create_contest. Both take the fields listed in the MCP reference. To start from a product, suggest_contest drafts that body for you.
POST /v1/contests/suggest
MCP tool: suggest_contest. Drafts a contest from a product without creating anything. Body: url (a product page: the store's, an Amazon page, any product page) or, for stores, product_id. Reads the product, writes a catchy name, the prize_name and a casual prize_description with the product's highlights, takes the price as prize_value_cents, copies the photos to the Winzos CDN as image_url (primary) and image_urls (the whole gallery), sets prize_url to the link you gave (or, from a store product_id, the product's page), and recommends min_participants and min_entries_per_user from the value. Answers input (add ends_at and pass it to validate_contest), product, rationale, warnings and next_step. For a store, input.product_id is set only when the product is in the store's catalog. Takes 5 to 40 seconds; 10 runs per key per hour. Works with any key.
curl -X POST https://api.winzos.io/v1/contests/suggest \
-H "Authorization: Bearer wz_live_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://www.amazon.com/dp/B09B8V1LZ3"}'POST /v1/contests/validate
MCP tool: validate_contest. Checks a contest without creating anything. Returns ready, missing_fields, errors and summary. Works with any key.
POST /v1/contests
MCP tool: create_contest. Creates the contest and answers 201 with contest, share_url and next_steps. If anything is missing or invalid it answers 422 and creates nothing.
curl -X POST https://api.winzos.io/v1/contests \
-H "Authorization: Bearer wz_live_your_key" \
-H "Content-Type: application/json" \
-d '{"prize_name": "Signed poster", "prize_description": "A poster signed by me", "prize_value_cents": 4000, "image_url": "https://example.com/poster.jpg", "ends_at": "2026-11-30T23:00:00Z"}'PATCH /v1/contests/{id}
MCP tool: update_contest. Body: only the fields to change (see Editing a contest). A live contest can change only name, prize_description, prize_url, the image, is_public, reengagement_nudges, earning_types and a store-wide contest's launcher_label; an ended one can't change, which gives 409 with data.editable_fields. Returns the contest and the fields changed.
curl -X PATCH https://api.winzos.io/v1/contests/3f2b8c1e-9a4d-4e7b-b1c2-5d6e7f8a9b0c \
-H "Authorization: Bearer wz_live_your_key" \
-H "Content-Type: application/json" \
-d '{"prize_description": "Now signed by the whole team"}'PATCH /v1/contests/{id}/visibility
MCP tool: set_contest_visibility. Body: {"is_public": false}. Private contests aren't listed on Winzos but keep running: their link, embeds and store page still work. Making a contest public needs the creator's public profile; without one the call answers 422 PUBLIC_PROFILE_REQUIRED.
POST /v1/images
MCP tool: upload_image. Body: image_url or image_base64. Returns image_url on the Winzos CDN. The contest endpoints take images directly, so you rarely need this.
Store products
GET /v1/products
MCP tool: list_products. Stores only. Searches active products by name.
| Parameter | Description |
|---|---|
query | Words from the product name. |
limit | Up to 50. Default 10. |
GET /v1/products/resolve
MCP tool: resolve_product. Stores only. The product for a link in your store.
| Parameter | Description |
|---|---|
url | For example https://yourstore.com/products/blue-hoodie. |
Reports
GET /v1/reports/summary
MCP tool: get_summary. Contests by status, plus participants (each person counted once), entries, actions and earnings across all your contests. Totals are all-time unless from/to narrow them.
GET /v1/reports/earnings
MCP tool: get_earnings. lifetime_earnings, period_earnings (with from/to), balance (ready to withdraw), pending_payouts and paid_out.
| Parameter | Description |
|---|---|
from, to | Optional dates for period_earnings and the breakdown. |
group_by | contest adds by_contest; day adds by_day. |
GET /v1/activity
MCP tool: get_activity. Recent events, newest first: entries, and contests starting or ending.
| Parameter | Description |
|---|---|
contest_id | Only this contest (its id). |
since | Only events at or after this ISO 8601 time. |
limit | Up to 100. Default 25. |