Sweeppea API

A REST API for managing sweepstakes, participants, winners and promotional campaigns. 108 endpoints, one API key, JSON in and out.

Quickstart OpenAPI 3.1 spec

Base URL

Every endpoint is served over HTTPS from a single host:

https://api-v3.sweeppea.com

Authentication

All requests must include your API key in the Authorization header as a Bearer token. The key identifies your account, so keep it on your server and never ship it to a browser or a mobile app.

Authorization: Bearer YOUR_API_KEY

Parameter casing Request parameters are PascalCase (e.g. SweepstakesToken). For backward compatibility, camelCase equivalents are also accepted.

Quickstart

Check that your key works with the Health Check endpoint:

curl -X POST "https://api-v3.sweeppea.com/account/health-check" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

const response = await fetch('https://api-v3.sweeppea.com/account/health-check', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

console.log(await response.json());

import requests

response = requests.post(
    "https://api-v3.sweeppea.com/account/health-check",
    headers={"Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json"}
)
print(response.json())

Every response uses the same envelope. Response tells you whether the call succeeded, Message explains the outcome, and successful calls report your monthly usage in Telemetry:

{
  "Response": true,
  "Message": "API is healthy",
  "Telemetry": {
    "DataConsumed": 0,
    "APICalls": 142,
    "MaxAPICalls": 500000
  }
}

Calls are limited per minute and per month by your plan. Read Concurrency & Rate Limiting before running anything in bulk.

API Reference

Browse by resource, or press Ctrl K to jump straight to any endpoint.

Account

Check connectivity and read the account, business and plan behind your API key.

4 endpoints → Entry Page

Read the registration form of a sweepstakes and update its entry page settings.

3 endpoints → Sweepstakes

Create, clone, update, pause and delete promotions.

7 endpoints → Participants

Add, search, count and remove entries, manage groups and bonus entries.

10 endpoints → Winners

Draw winners at random, schedule drawings and read the results.

5 endpoints → Codes & Coupons

Create, generate, assign, redeem and send coupon codes, and configure how a sweepstakes hands them out.

14 endpoints → Surveys

Build question sets, collect responses and read aggregated reports.

7 endpoints → Rules

Create official rules from HTML or with the guided wizard.

5 endpoints → Files

Upload files, list them, get secure links and send them by email.

5 endpoints → Invoices

Issue, update and track invoices.

5 endpoints → Messaging

Read email and SMS campaigns and reports, manage suppressions and message a participant.

12 endpoints → Notes

Encrypted notes for your account.

5 endpoints → Calendar

Create and manage calendar events.

5 endpoints → Billing

Billing transactions, consumptions and data transfer.

3 endpoints → Wallet

Your wallet movements.

1 endpoint → To-Do's

A simple task list for your team.

4 endpoints → Support

Open, follow and resolve support tickets.

7 endpoints → Help & Support

Search the Sweeppea help documentation.

1 endpoint → Tools

Reference data: timezones, US states, zip codes, area codes and countries.

5 endpoints →

The Sweeppea Developer Ecosystem

Three clients, one platform, one API key. All of them talk to this same REST API v3 — pick whichever fits how you work.

REST API v3

Direct HTTP integration, with a full OpenAPI 3.1 specification.

apidocs.sweeppea.com · you are here

MCP Server

71 tools for AI assistants — Claude, Cursor, Windsurf, Gemini CLI and more.

mcpdocs.sweeppea.com ↗ CLI

A native binary for your shell and CI — npx @sweeppea/cli, JSON output everywhere.

clidocs.sweeppea.com ↗

MCP Server

Sweeppea Renaissance includes a full Model Context Protocol (MCP) Server implementation, allowing you to integrate the entire platform with any LLM or AI-powered application.

Connect your AI assistants, chatbots, autonomous agents, or any device that communicates with an LLM to manage sweepstakes, participants, winners, and more — all through natural language.

With the MCP Server, your AI can access every Sweeppea tool programmatically, making it possible to operate the platform from any device or robot connected to a language model.

Quick Start

Get up and running with the MCP Server in minutes.

View Guide → Tools

Explore all available MCP tools and their capabilities.

View Tools → Examples

Real-world usage examples and integration patterns.

View Examples → Platforms

Supported platforms and compatibility information.

View Platforms → Protocol

Technical details about the MCP protocol specification.

View Protocol → Showcase

See what others are building with the Sweeppea MCP Server.

View Showcase →

Command Line Interface (CLI)

The official Sweeppea CLI puts the same API in your terminal. It is a single native binary (written in Rust) distributed on npm — no runtime to install, instant startup.

Use it interactively or in CI: every command supports --json for machine-readable output, and destructive actions confirm first and honor --yes.

npx @sweeppea/cli auth login

Install

Prebuilt binaries for Linux, macOS and Windows via npm.

View Install → Authentication

Your API key, validated and stored in the OS keyring.

View Auth → Commands

13 resource categories — full parity with the MCP Server.

View Commands →