{"openapi":"3.1.0","info":{"title":"Winzos API","version":"1.0.0","description":"Create contests and read their reports for your own Winzos account. Every request needs an API key from Settings → API keys in Winzos Manage."},"servers":[{"url":"https://api.winzos.io"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Winzos API key (wz_live_...), from Settings → API keys in Winzos Manage."},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"The same key as a query parameter, for clients that cannot set headers."}},"schemas":{},"parameters":{}},"paths":{"/v1/me":{"get":{"operationId":"get_account","summary":"Get the account this API key belongs to","description":"Returns the Winzos account behind this API key: its name, whether it is a store (a Shopify merchant whose contests give away their own products) or a creator (an influencer who runs contests for a prize they describe), and what this key may do. Call this first, before creating a contest, because stores and creators create contests differently.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/products":{"get":{"operationId":"list_products","summary":"Search the store's products","description":"Stores only. Searches the store's active Shopify products by name and returns each with its product_id, price, image, link and whether it can be a contest prize (eligible: active, has an image, and in stock or never out of stock, like a gift card or a product that keeps selling without stock). Use it when the user names a product instead of linking it, show them the matches, and pass the chosen product_id to validate_contest.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Words from the product's name. Leave out to list recent products."},"required":false,"description":"Words from the product's name. Leave out to list recent products.","name":"query","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Products to return, up to 50."},"required":false,"description":"Products to return, up to 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/products/resolve":{"get":{"operationId":"resolve_product","summary":"Look up a product from its link","description":"Stores only. Turns a link to a product in the store (for example https://yourstore.com/products/blue-hoodie, with or without ?variant=) into the product: its product_id, title, price, image and whether it can be a contest prize. The link must be to this store.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","format":"uri","description":"The product's link in your store."},"required":true,"description":"The product's link in your store.","name":"url","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/images":{"post":{"operationId":"upload_image","summary":"Upload a contest image","description":"Stores an image on the Winzos CDN and returns its image_url. You rarely need this: validate_contest and create_contest take image_url or image_base64 directly. Send exactly one of image_url (an https link Winzos downloads) or image_base64 (the file, base64 or a data: URI). JPEG, PNG, GIF or WebP, up to 10 MB.","tags":["Changes (full access keys)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"image_url":{"type":"string","format":"uri","description":"An https link to the image."},"image_base64":{"type":"string","description":"The image, base64 or a data: URI."}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/contests/suggest":{"post":{"operationId":"suggest_contest","summary":"Draft a contest from a product link","description":"Drafts a contest from a product, without creating anything. Give it a link to a product page (a page in the store, an Amazon page, or any product page) and it reads the product, writes a catchy contest name, the prize name and a casual description with the product's highlights, takes the price as the value, copies the product photo to the Winzos CDN, and recommends min_participants and min_entries_per_user from the prize's value. Stores can give a product_id from list_products instead of a link. Returns `input`, ready for validate_contest once ends_at is added, plus the product it read, a rationale for the minimums and warnings to pass on (for example a price not in US dollars). For a store, `input.product_id` is set when the product is in the store's catalog; if it isn't, ask the user which store product the contest is for and use list_products. Takes 5 to 40 seconds. Use it whenever the user mentions a product link or asks you to write the contest for them.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"The product's link: a page in the store, an Amazon page, or any product page."},"product_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"string","pattern":"^\\d+$"}],"description":"Stores: a Shopify product id from list_products, instead of a link."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/contests/validate":{"post":{"operationId":"validate_contest","summary":"Check a contest before creating it","description":"Checks a contest without creating it, and fills in what Winzos can: for a store, the prize name, description, value and image come from the product. Returns ready (true when create_contest would succeed), missing_fields (each with a question to ask the user), errors, and a summary to show the user. Always call this before create_contest, ask only for what is missing, and get the user's confirmation of the summary.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Contest title. Defaults to '<prize name> Giveaway'."},"product_url":{"type":"string","format":"uri","description":"Stores: a link to the product in your store, e.g. https://yourstore.com/products/blue-hoodie."},"product_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"string","pattern":"^\\d+$"}],"description":"Stores: the Shopify product id, from list_products. Use instead of product_url."},"prize_name":{"type":"string","minLength":1,"maxLength":255,"description":"What the winner gets. Creators: required. Stores: defaults to the product title."},"prize_description":{"type":"string","minLength":1,"maxLength":1000,"description":"A short description of the prize. Creators: required. Stores: defaults to the product description."},"prize_value_cents":{"type":["integer","null"],"minimum":0,"description":"Retail value of the prize in US cents (7500 = $75). Creators: required, 0 if unknown. Stores: defaults to the product price."},"image_url":{"type":"string","format":"uri","description":"An https link to the prize image. Winzos downloads and stores a copy."},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":8,"description":"More prize photos, as https links, primary (image_url) first: the gallery the contest page shows. Up to 8. suggest_contest returns these for a product link; pass them on to keep the gallery."},"image_base64":{"type":"string","description":"The prize image itself, base64 or a data: URI (JPEG, PNG, GIF or WebP, up to 10 MB). Use when the user attached an image."},"prize_url":{"type":["string","null"],"format":"uri","description":"A link where people can see or buy the prize: an http or https address, shown as 'View product' on the contest page. Stores: defaults to the product's page in the store. Send null to leave it empty."},"starts_at":{"type":"string","format":"date-time","description":"When the contest starts, ISO 8601 with a time zone. Leave out to start now."},"ends_at":{"type":"string","format":"date-time","description":"When the contest ends, ISO 8601 with a time zone. Required."},"number_of_winners":{"type":"integer","minimum":1,"maximum":100,"description":"How many winners are drawn. Default 1."},"min_participants":{"type":"integer","minimum":1,"maximum":10000,"description":"The minimum number of people who must enter. Binds only with enforce_min_participants: then the contest ends with no draw (no winner, no prize) if fewer enter, and the contest page says so before anyone enters. Without it the number is ignored. Default 10. With enforce_min_participants, must be at least number_of_winners."},"enforce_min_participants":{"type":"boolean","description":"Make min_participants binding: no draw if fewer people enter. Default false. Honored only while Winzos allows minimums; when it doesn't, the contest is created without one and comes back with min_participants null. Ask the user before turning it on: entrants are told up front, and a contest below the minimum awards nothing."},"min_entries_per_user":{"type":"integer","minimum":1,"maximum":100,"description":"Entries a participant needs to qualify. Default 1."},"participation_prize":{"type":"string","enum":["none","product_coupon","store_coupon"],"description":"Stores only: a coupon every participant gets. Default 'none'."},"is_public":{"type":"boolean","description":"List the contest publicly on Winzos. Needs the creator's public profile (name and type, in Winzos Manage → Settings → Public profile). Default true when they have one, false when they don't. The share link works either way."},"store_wide":{"type":"boolean","description":"Stores only: show this contest's launch button on every product page in the store that has the Winzos block, not only on the prize product's page (e.g. a gift card giveaway). A product with its own live contest shows that one instead. A store runs one live or scheduled store-wide contest at a time; while one exists this fails, and the user ends it early (or archives it, if it hasn't started) in Winzos Manage. Can't be changed after creation. Default false."},"launcher_label":{"type":"string","maxLength":60,"description":"Store-wide contests only: the launch button's text, in place of the label set in the Widget Builder, e.g. \"Win a $100 gift card\". Up to 60 characters. Leave out to use the Widget Builder's label."},"reengagement_nudges":{"type":"boolean","description":"Re-engagement nudges: Email people who earned entries a reminder to come back and collect more while the contest is live, and a last call a day before it closes. On by default. They can unsubscribe from these emails. Default true; set false only when the user asks."},"earning_types":{"type":"array","items":{"type":"string","enum":["surveys","games","offers"]},"minItems":1,"maxItems":3,"description":"Ways to earn: which kinds of actions people can do for entries: \"surveys\" (short surveys), \"games\" (mobile and web games) and \"offers\" (sign-ups, apps and trials). Default all three; at least one. Set it only when the user wants some kinds left out, e.g. [\"surveys\"] for a surveys-only contest."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/contests":{"post":{"operationId":"create_contest","summary":"Create a contest","description":"Creates the contest. It goes live straight away, or at starts_at. Only call this after validate_contest returned ready and the user confirmed its summary. Takes the same input as validate_contest. Returns the contest, its share_url, and next_steps to tell the user: for a creator, the link to share; for a store, where the contest appears and the link to install Winzos in the store if they haven't.","tags":["Changes (full access keys)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"Contest title. Defaults to '<prize name> Giveaway'."},"product_url":{"type":"string","format":"uri","description":"Stores: a link to the product in your store, e.g. https://yourstore.com/products/blue-hoodie."},"product_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"string","pattern":"^\\d+$"}],"description":"Stores: the Shopify product id, from list_products. Use instead of product_url."},"prize_name":{"type":"string","minLength":1,"maxLength":255,"description":"What the winner gets. Creators: required. Stores: defaults to the product title."},"prize_description":{"type":"string","minLength":1,"maxLength":1000,"description":"A short description of the prize. Creators: required. Stores: defaults to the product description."},"prize_value_cents":{"type":["integer","null"],"minimum":0,"description":"Retail value of the prize in US cents (7500 = $75). Creators: required, 0 if unknown. Stores: defaults to the product price."},"image_url":{"type":"string","format":"uri","description":"An https link to the prize image. Winzos downloads and stores a copy."},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":8,"description":"More prize photos, as https links, primary (image_url) first: the gallery the contest page shows. Up to 8. suggest_contest returns these for a product link; pass them on to keep the gallery."},"image_base64":{"type":"string","description":"The prize image itself, base64 or a data: URI (JPEG, PNG, GIF or WebP, up to 10 MB). Use when the user attached an image."},"prize_url":{"type":["string","null"],"format":"uri","description":"A link where people can see or buy the prize: an http or https address, shown as 'View product' on the contest page. Stores: defaults to the product's page in the store. Send null to leave it empty."},"starts_at":{"type":"string","format":"date-time","description":"When the contest starts, ISO 8601 with a time zone. Leave out to start now."},"ends_at":{"type":"string","format":"date-time","description":"When the contest ends, ISO 8601 with a time zone. Required."},"number_of_winners":{"type":"integer","minimum":1,"maximum":100,"description":"How many winners are drawn. Default 1."},"min_participants":{"type":"integer","minimum":1,"maximum":10000,"description":"The minimum number of people who must enter. Binds only with enforce_min_participants: then the contest ends with no draw (no winner, no prize) if fewer enter, and the contest page says so before anyone enters. Without it the number is ignored. Default 10. With enforce_min_participants, must be at least number_of_winners."},"enforce_min_participants":{"type":"boolean","description":"Make min_participants binding: no draw if fewer people enter. Default false. Honored only while Winzos allows minimums; when it doesn't, the contest is created without one and comes back with min_participants null. Ask the user before turning it on: entrants are told up front, and a contest below the minimum awards nothing."},"min_entries_per_user":{"type":"integer","minimum":1,"maximum":100,"description":"Entries a participant needs to qualify. Default 1."},"participation_prize":{"type":"string","enum":["none","product_coupon","store_coupon"],"description":"Stores only: a coupon every participant gets. Default 'none'."},"is_public":{"type":"boolean","description":"List the contest publicly on Winzos. Needs the creator's public profile (name and type, in Winzos Manage → Settings → Public profile). Default true when they have one, false when they don't. The share link works either way."},"store_wide":{"type":"boolean","description":"Stores only: show this contest's launch button on every product page in the store that has the Winzos block, not only on the prize product's page (e.g. a gift card giveaway). A product with its own live contest shows that one instead. A store runs one live or scheduled store-wide contest at a time; while one exists this fails, and the user ends it early (or archives it, if it hasn't started) in Winzos Manage. Can't be changed after creation. Default false."},"launcher_label":{"type":"string","maxLength":60,"description":"Store-wide contests only: the launch button's text, in place of the label set in the Widget Builder, e.g. \"Win a $100 gift card\". Up to 60 characters. Leave out to use the Widget Builder's label."},"reengagement_nudges":{"type":"boolean","description":"Re-engagement nudges: Email people who earned entries a reminder to come back and collect more while the contest is live, and a last call a day before it closes. On by default. They can unsubscribe from these emails. Default true; set false only when the user asks."},"earning_types":{"type":"array","items":{"type":"string","enum":["surveys","games","offers"]},"minItems":1,"maxItems":3,"description":"Ways to earn: which kinds of actions people can do for entries: \"surveys\" (short surveys), \"games\" (mobile and web games) and \"offers\" (sign-ups, apps and trials). Default all three; at least one. Set it only when the user wants some kinds left out, e.g. [\"surveys\"] for a surveys-only contest."}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}},"get":{"operationId":"list_contests","summary":"List contests","description":"Lists the account's contests, newest first, each with all-time stats (participants, entries, actions completed, earnings) and its share link. Filter by status ('live', 'scheduled', 'ended') or by name with search. For contests ending soon, pass status 'live', ends_within_hours (for example 72) and sort 'ends_at' with order 'asc'. pagination.total_count answers 'how many'.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","enum":["scheduled","live","ended"],"description":"Only contests in this state."},"required":false,"description":"Only contests in this state.","name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Match contest or prize names containing this text."},"required":false,"description":"Match contest or prize names containing this text.","name":"search","in":"query"},{"schema":{"type":"boolean","description":"Only public (true) or private (false) contests."},"required":false,"description":"Only public (true) or private (false) contests.","name":"is_public","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":8760,"description":"Only contests whose end is between now and this many hours from now."},"required":false,"description":"Only contests whose end is between now and this many hours from now.","name":"ends_within_hours","in":"query"},{"schema":{"type":"string","enum":["created_at","starts_at","ends_at","name"],"default":"created_at"},"required":false,"name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"required":false,"name":"order","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number, starting at 1."},"required":false,"description":"Page number, starting at 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"Results per page, up to 100."},"required":false,"description":"Results per page, up to 100.","name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/contests/{id}":{"patch":{"operationId":"update_contest","summary":"Edit a contest","description":"Changes a contest's details. Send only the fields to change. A scheduled contest can change everything except its start and end times and its product. A live contest can only change its title (name), image, prize description, prize_url (the link to see or buy the prize), whether it is public, its reengagement_nudges, its earning_types (ways to earn) and (store-wide contests) its launcher_label, because people have already entered under its terms. An ended contest can't be changed. get_contest lists the contest's editable_fields. Tell the user what will change and get their OK before calling this. Winners are handled in Winzos Manage, not here.","tags":["Changes (full access keys)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","description":"The contest id: the `id` a contest comes back with."},"required":true,"description":"The contest id: the `id` a contest comes back with.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255,"description":"New contest title. Live contests can change it too."},"prize_name":{"type":"string","minLength":1,"maxLength":255,"description":"New prize name. Scheduled contests only."},"prize_description":{"type":"string","minLength":1,"maxLength":1000,"description":"New prize description."},"prize_url":{"type":["string","null"],"format":"uri","description":"A link where people can see or buy the prize: an http or https address, shown as 'View product' on the contest page. Live contests can change it too. null removes it."},"prize_value_cents":{"type":["integer","null"],"minimum":0,"description":"New prize value in US cents. Scheduled contests only."},"image_url":{"type":"string","format":"uri","description":"A new prize image, as an https link. Winzos downloads and stores a copy."},"image_base64":{"type":"string","description":"A new prize image, base64 or a data: URI (JPEG, PNG, GIF or WebP, up to 10 MB)."},"image_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":8,"description":"The prize photo gallery, as https links, primary (image_url) first. Replaces the whole gallery; send [] to clear it."},"number_of_winners":{"type":"integer","minimum":1,"maximum":100,"description":"Scheduled contests only."},"min_participants":{"type":"integer","minimum":1,"maximum":10000,"description":"Scheduled contests only. Binds only with enforce_min_participants."},"enforce_min_participants":{"type":"boolean","description":"Scheduled contests only. Make min_participants binding (no draw if fewer people enter) or not. Honored only while Winzos allows minimums. Get the user's OK first."},"min_entries_per_user":{"type":"integer","minimum":1,"maximum":100,"description":"Scheduled contests only."},"participation_prize":{"type":"string","enum":["none","product_coupon","store_coupon"],"description":"Stores only, scheduled contests only."},"is_public":{"type":"boolean","description":"List the contest publicly on Winzos (true; needs the creator's public profile, else PUBLIC_PROFILE_REQUIRED) or keep it unlisted (false)."},"launcher_label":{"type":["string","null"],"maxLength":60,"description":"Store-wide contests only, live ones included: the launch button's text, up to 60 characters. null or \"\" goes back to the label set in the Widget Builder."},"reengagement_nudges":{"type":"boolean","description":"Re-engagement nudges: Email people who earned entries a reminder to come back and collect more while the contest is live, and a last call a day before it closes. On by default. They can unsubscribe from these emails. Live contests can change it too."},"earning_types":{"type":"array","items":{"type":"string","enum":["surveys","games","offers"]},"minItems":1,"maxItems":3,"description":"Ways to earn: which kinds of actions people can do for entries: \"surveys\", \"games\", \"offers\". At least one. Live contests can change it too; entries already earned stay."}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}},"get":{"operationId":"get_contest","summary":"Get one contest with its stats","description":"Returns one contest with its stats: participants (different people who entered), entries, actions completed and earnings. Stats are all-time unless from and/or to (YYYY-MM-DD, UTC) narrow them. editable_fields lists what update_contest can change right now. If you only have a contest's name, find its id with list_contests and search.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","description":"The contest id: the `id` a contest comes back with."},"required":true,"description":"The contest id: the `id` a contest comes back with.","name":"id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include, YYYY-MM-DD (UTC). Leave out for all time."},"required":false,"description":"First day to include, YYYY-MM-DD (UTC). Leave out for all time.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include, YYYY-MM-DD (UTC). Defaults to today."},"required":false,"description":"Last day to include, YYYY-MM-DD (UTC). Defaults to today.","name":"to","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/contests/{id}/visibility":{"patch":{"operationId":"set_contest_visibility","summary":"Make a contest public or private","description":"Makes a contest public (listed on Winzos) or private (not listed). This is the same switch as Make Public in Winzos Manage. The share link, embeds and store page keep working either way, so a private contest is still running. Use it when the user wants more time before the contest is listed. Making a contest public needs the creator's public profile (name and type); without it the call fails with PUBLIC_PROFILE_REQUIRED, and the creator adds one in Winzos Manage → Settings → Public profile. Making a contest private always works.","tags":["Changes (full access keys)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","description":"The contest id: the `id` a contest comes back with."},"required":true,"description":"The contest id: the `id` a contest comes back with.","name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"is_public":{"type":"boolean","description":"true to list the contest on Winzos (needs the creator's public profile), false to keep it unlisted."}},"required":["is_public"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/contests/{id}/winners":{"get":{"operationId":"list_winners","summary":"List a contest's winners","description":"Lists the winners of an ended contest in rank order, with their claim status ('pending', 'notified', 'claimed', 'fulfilled', 'forfeited') and claim deadline. Winners are named by first name and last initial only. A contest that has not ended has no winners yet. This is read-only: notifying winners, fulfilling prizes and sending coupons are done in Winzos Manage, so send the user there for those.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","description":"The contest id: the `id` a contest comes back with."},"required":true,"description":"The contest id: the `id` a contest comes back with.","name":"id","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/reports/summary":{"get":{"operationId":"get_summary","summary":"Get an account summary","description":"Answers 'how is it going': how many contests are live, scheduled and ended right now, and, across all contests, how many different people took part, how many entries they earned, how many actions they completed and how much the account earned. Totals are all-time unless from and/or to (YYYY-MM-DD, UTC) narrow them; the contest counts are always current.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include, YYYY-MM-DD (UTC). Leave out for all time."},"required":false,"description":"First day to include, YYYY-MM-DD (UTC). Leave out for all time.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include, YYYY-MM-DD (UTC). Defaults to today."},"required":false,"description":"Last day to include, YYYY-MM-DD (UTC). Defaults to today.","name":"to","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/reports/earnings":{"get":{"operationId":"get_earnings","summary":"Get earnings and payouts","description":"Answers 'how much have I made'. Returns lifetime earnings across all contests (the account's own share), earnings in a date range when from and/or to are given, the balance available to withdraw, withdrawals on their way and the total paid out. group_by 'contest' adds earnings per contest, highest first; group_by 'day' adds earnings per UTC day.","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"First day to include, YYYY-MM-DD (UTC). Leave out for all time."},"required":false,"description":"First day to include, YYYY-MM-DD (UTC). Leave out for all time.","name":"from","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Last day to include, YYYY-MM-DD (UTC). Defaults to today."},"required":false,"description":"Last day to include, YYYY-MM-DD (UTC). Defaults to today.","name":"to","in":"query"},{"schema":{"type":"string","enum":["contest","day"],"description":"Add a breakdown per contest or per day."},"required":false,"description":"Add a breakdown per contest or per day.","name":"group_by","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}},"/v1/activity":{"get":{"operationId":"get_activity","summary":"Get recent activity","description":"Recent activity, newest first: participants earning entries (named by first name and last initial), and contests starting or ending. Narrow it to one contest with contest_id, or to events after a moment with since (an ISO 8601 date-time, e.g. 2026-10-30T00:00:00Z).","tags":["Reports (any key)"],"security":[{"bearer":[]},{"apiKeyQuery":[]}],"parameters":[{"schema":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"string"}],"description":"Only this contest's activity: its id, as a contest comes back with."},"required":false,"description":"Only this contest's activity: its id, as a contest comes back with.","name":"contest_id","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only events at or after this ISO 8601 date-time."},"required":false,"description":"Only events at or after this ISO 8601 date-time.","name":"since","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Events to return, up to 100."},"required":false,"description":"Events to return, up to 100.","name":"limit","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"401":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"403":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"404":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"422":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}},"429":{"description":"The shared error envelope: success false, message, code and statusCode.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"number"},"data":{}},"required":["success","message","code","statusCode"]}}}}}}}},"webhooks":{}}