Welcome to Uplup API

Build powerful applications with our comprehensive REST API. Create interactive wheels, manage entries, track analytics, and more with simple HTTP requests.

Get API Keys View API Reference

Quick Start

Get API Keys

Generate keys

Make Requests

Use your API key to authenticate requests to our REST endpoints.

Learn authentication →

Build & Ship

Create wheels, manage entries, and integrate our tools into your applications.

Explore endpoints →

Try it out

List your wheels - JavaScript

// Using Basic Authentication
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';

const credentials = btoa(`${apiKey}:${apiSecret}`);
const response = await fetch(
  'https://api.uplup.com/api/wheel',
  {
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    }
  }
);

const data = await response.json();
console.log('Your wheels:', data);

What you can build

Interactive Decision Wheels

Create customizable spinning wheels for contests, games, random selection, and decision-making tools.

Entry Management

Dynamically add, remove, and modify wheel entries through API calls or CSV imports.

Real-time Results

Get instant results from wheel spins with detailed analytics and winner tracking.

Webhook Integration

Receive real-time notifications when wheels are spun, winners are selected, or entries change.

Embeddable Widgets

Embed interactive wheels directly into your website or application with our embed API.

Analytics & Insights

Track usage patterns, popular entries, and engagement metrics to optimize your wheels.

API Information

Base URL

https://api.uplup.com

API Version

v1.0 - StableREST API with JSON

Authentication

Authenticate your API requests using your Uplup API key and secret with Basic Authentication.

API Credentials

Two-Part Authentication

Every API request requires both:

API Key: Public identifier following the format uplup_[env]_[32_characters]
API Secret: Private authentication token (keep this secure!)

LIVEuplup_live_abc123def456...

Production environment - Use for live applications

TESTuplup_test_xyz789abc123...

Development environment - Use for testing and development

Authentication Methods

We recommend using HTTP Basic Authentication for security. The API key serves as the username and the secret as the password.

Authentication Examples - JavaScript

// Basic Authentication (Recommended)
const apiKey = 'uplup_live_abc123def456789...';
const apiSecret = 'your_api_secret_here...';

// Using fetch with Basic Auth
const credentials = btoa(`${apiKey}:${apiSecret}`);
const response = await fetch(
  'https://api.uplup.com/api/wheel',
  {
    headers: {
      'Authorization': `Basic ${credentials}`,
      'Content-Type': 'application/json'
    }
  }
);

// Using axios with Basic Auth
import axios from 'axios';

const api = axios.create({
  baseURL: 'https://api.uplup.com',
  auth: {
    username: apiKey,
    password: apiSecret
  },
  headers: {
    'Content-Type': 'application/json'
  }
});

const wheels = await api.get('/api/wheel');

// Alternative: Query parameters (less secure)
const response = await fetch(
  `https://api.uplup.com/api/wheel?api_key=${apiKey}&api_secret=${apiSecret}`
);

Security Best Practices

Never expose API keys in client-side code

Always make API calls from your backend server. API keys should never be visible in browser code, mobile apps, or public repositories.

Do This

• Store API keys in environment variables
• Use HTTPS for all API requests
• Implement proper error handling
• Rotate keys regularly
• Use test keys for development

Avoid This

• Hardcoding keys in source code
• Committing keys to version control
• Sharing keys via email or chat
• Using live keys in development
• Making requests from frontend

Error Handling

The API uses standard HTTP response codes to indicate success or failure. All error responses include a consistent JSON structure with detailed error information.

Error Response Format

{
  "success": false,
  "error": {
    "code": 401,
    "message": "Invalid API key provided",
    "details": {           // Optional: Additional error context
      "field": "api_key",
      "reason": "malformed"
    },
    "retry_after": 60      // Optional: For rate limit errors (429)
  }
}

Complete Error Code Reference

2xx Success

200

Request succeeded

201

Created

Resource created successfully

204

No Content

Request succeeded with no response body

4xx Client Errors

400

Bad Request

Invalid request format or parameters

401

Unauthorized

Missing or invalid API key

403

Forbidden

Valid API key but insufficient permissions

404

Not Found

Resource not found

422

Unprocessable Entity

Valid format but semantic errors

429

Too Many Requests

Rate limit exceeded

5xx Server Errors

500

Internal Server Error

Unexpected server error

502

Bad Gateway

Invalid response from upstream server

503

Service Unavailable

Service temporarily unavailable

504

Gateway Timeout

Request timeout

Common Authentication Errors

401Unauthorized

Invalid API key or missing Authorization header

403Forbidden

Plan upgrade required (API access needs Boost plan or higher)

429Too Many Requests

Rate limit exceeded (see rate limiting section for details)

Error Handling Example - JavaScript

// Handle authentication errors
try {
  const response = await fetch(
    'https://api.uplup.com/api/wheel/wheels?api_key=invalid_key',
    {
      headers: {
        'Content-Type': 'application/json'
      }
    }
  );

  if (response.status === 401) {
    console.log('Invalid API key');
  } else if (response.status === 403) {
    console.log('Plan upgrade required');
  } else if (response.status === 429) {
    console.log('Rate limit exceeded');
  }

  const data = await response.json();
  if (!data.success) {
    console.error('API Error:', data.error.message);
  }
} catch (error) {
  console.error('Network error:', error);
}

Important: API access requires a Boost plan or higher. Free plan users cannot generate or use API keys. Attempting to use the API with a Free plan will return a 403 error.

Rate Limiting

Limits by Plan

Rate limits are enforced per API key. Exceeding limits will return a 429 error.

Boost Plan

(Minimum required for API)

• 1,000 requests/hour
• 100 requests/minute
• 5 API keys max

Elevate Plan

• 10,000 requests/hour
• 1,000 requests/minute
• 10 API keys max

Ultimate Plan

• 50,000 requests/hour
• 5,000 requests/minute
• Unlimited API keys

Ready to get started?

Generate your API keys from the Uplup dashboard and start building amazing applications.

Generate API Keys View Plans & Pricing

Wheel API

Create, manage, and interact with spinning wheels programmatically. Build decision-making tools, contests, games, and interactive experiences.

Base URL: https://api.uplup.com/api/wheel

GET

List Wheels

/api/wheel/wheels

Retrieve a paginated list of all wheels belonging to your account.

GET List Wheels - JavaScript

// Get all wheels with pagination
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const response =
await fetch('https://api.uplup.com/api/wheel/wheels', {
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "data": {"wheels": [...]}}
  console.log('Response:', JSON.stringify(data, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (data.error) {
    console.error('Message:', data.error.message);
  }
}

POST

Create Wheel

/api/wheel/wheels

Create a new spinning wheel with customizable entries, settings, and appearance.

Entries can be simple strings or objects with additional metadata like weights or colors.

Maximum of 1000 entries per wheel. Large wheels may impact performance.

POST Create Wheel - JavaScript

// Create a new wheel
const wheelData = {
  wheel_name: "Team Lunch Picker",
  entries: ["Pizza Palace", "Burger Barn", "Taco Town", "Sushi Spot"],
  settings: {
    spinnerDuration: "normal",
    selectedColorSet: "Vibrant",
    colorSequence: ["#e6194b", "#3cb44b", "#ffe119", "#4363d8"],
    selectedAudio: "https://uplup-media.ams3.digitaloceanspaces.com/root/drum-roll-long.mp3",
    volume: 100,
    showTitle: true,
    removeAfterWin: false,
    winnersToSelect: 1
  }
};

const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const response = await fetch(
  'https://api.uplup.com/api/wheel/wheels', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(wheelData) // Follows redirects automatically
});

const result = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "data": {"wheel_id": "wheel_123", "message": "Wheel created successfully"}}
  console.log('Response:', JSON.stringify(result, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (result.error) {
    console.error('Message:', result.error.message);
  }
}

GET

Get Wheel

/api/wheel/wheels/{wheel_id}

Retrieve detailed information about a specific wheel including all entries and settings.

GET Get Wheel - JavaScript

// Get detailed wheel information
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const wheelId = 'wheel_123';
const response = await fetch(
  `https://api.uplup.com/api/wheel/wheels/${wheelId}`, {
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
}) // Follows redirects automatically;

const wheel = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "data": {wheel details}}
  console.log('Response:', JSON.stringify(wheel, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (wheel.error) {
    console.error('Message:', wheel.error.message);
  }
}

POST

Spin Wheel (Coming Soon)

/api/wheel/wheels/{wheel_id}/spin

Programmatically spin a wheel and get the random result. Optionally save the result and trigger webhooks. Note: This endpoint is not yet implemented and will return a 501 error.

The random algorithm ensures fair distribution based on entry weights.

Spinning wheels with many entries may take longer to process.

POST Spin Wheel (Coming Soon) - JavaScript

// Spin a wheel and get the result
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const wheelId = 'wheel_123';
const response = await fetch(
  `https://api.uplup.com/api/wheel/wheels/${wheelId}/spin`, {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    save_result: true,
    notify_webhooks: true
  }) // Follows redirects automatically
});

const result = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "data": {"winner": {...}, "results": [...]}}
  console.log('Response:', JSON.stringify(result, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (result.error) {
    console.error('Message:', result.error.message);
  }
}

PUT

Update Wheel

/api/wheel/wheels/{wheel_id}

Update an existing wheel's properties including title, entries, settings, and appearance.

PUT Update Wheel - JavaScript

// Update wheel name and add new entries
const updates = {
  wheel_name: "Updated Team Lunch Picker",
  entries: ["Pizza Palace", "Burger Barn", "Sushi Spot", "Deli Downtown"],
  settings: {
    spinnerDuration: "short",
    enableConfetti: false
  }
};

const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const wheelId = 'wheel_123';
const response = await fetch(
  `https://api.uplup.com/api/wheel/wheels/${wheelId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(updates) // Follows redirects automatically
});

const result = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "data": {"wheel_id": "wheel_123", "message": "Wheel created successfully"}}
  console.log('Response:', JSON.stringify(result, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (result.error) {
    console.error('Message:', result.error.message);
  }
}

DELETE

Delete Wheel

/api/wheel/wheels/{wheel_id}

Permanently delete a wheel and all its associated data including spin history.

This action is irreversible. All wheel data and history will be permanently deleted.

DELETE Delete Wheel - JavaScript

// Delete a wheel permanently
const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const wheelId = 'wheel_123';
const response = await fetch(
  `https://api.uplup.com/api/wheel/wheels/${wheelId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  }
}) // Follows redirects automatically;

const result = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "message": "Wheel deleted successfully"}
  console.log('Response:', JSON.stringify(result, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (result.error) {
    console.error('Message:', result.error.message);
  }
}

POST

Manage Entries (Coming Soon)

/api/wheel/wheels/{wheel_id}/entries

Add, update, or remove entries from a wheel without replacing the entire entries array. Note: This endpoint is not yet implemented and will return a 501 error.

POST Manage Entries (Coming Soon) - JavaScript

// Add new entries to a wheel
const entryUpdate = {
  action: "add",
  entries: ["Mediterranean Cafe", "BBQ Joint", "Vegan Kitchen"]
};

const apiKey = 'YOUR_API_KEY';
const apiSecret = 'YOUR_API_SECRET';
const credentials = btoa(`${apiKey}:${apiSecret}`);
const wheelId = 'wheel_123';
const response = await fetch(
  `https://api.uplup.com/api/wheel/wheels/${wheelId}/entries`, {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(entryUpdate) // Follows redirects automatically
});

const result = await response.json();

if (response.ok) {
  // Success - API returns JSON response
  // Format: {"success": true, "data": {"entries_added": 3, ...}}
  console.log('Response:', JSON.stringify(result, null, 2));
} else {
  // Handle error
  console.error('Error:', response.status);
  if (result.error) {
    console.error('Message:', result.error.message);
  }
}

// Remove specific entries
const removeUpdate = {
  action: "remove", 
  entries: ["entry_id_1", "entry_id_2"]
};

Getting Started

Quick Start Guide

Prerequisites

Authentication

API Key Format

Security Best Practices

Do This

Avoid This

Rate Limiting

Limits by Plan

Boost Plan

Elevate Plan

Ultimate Plan

Wheel API

Available Endpoints

List Wheels

Create Wheel

Get Wheel Details

Update Wheel

Delete Wheel

Spin Wheel

Manage Entries

Welcome to Uplup API

Quick Start

Get API Keys

Make Requests

Build & Ship

Try it out

What you can build

Interactive Decision Wheels

Entry Management

Real-time Results

Webhook Integration

Embeddable Widgets

Analytics & Insights

API Information

Base URL

API Version

Authentication

API Credentials

Authentication Methods

Security Best Practices

Do This

Avoid This

Error Handling

Error Response Format

Complete Error Code Reference

Common Authentication Errors

Rate Limiting

Limits by Plan

Boost Plan

Elevate Plan

Ultimate Plan

Ready to get started?

Wheel API

List Wheels

Create Wheel

Get Wheel

Spin Wheel (Coming Soon)

Update Wheel

Delete Wheel

Manage Entries (Coming Soon)