Skip to main content

​
List Active Giveaways

GET /giveaways

Retrieves all currently active public giveaways.
GET /giveaways
Authentication: None Response 
{
  "status": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "url": "giveaway-abc123",
        "name": "Unusual Hat Giveaway",
        "creator": "76561198000000000",
        "creator_name": "PlayerName",
        "creator_image": "https://avatars.steamstatic.com/...",
        "max_entries": 500,
        "current_entries": 150,
        "end_time": 1706832000,
        "items": [],
        "total_value": 50000
      }
    ]
  }
}

​
Giveaway History

GET /giveaways/history

Retrieves past (ended) public giveaways.
GET /giveaways/history
Authentication: None Response 
{
  "status": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "url": "giveaway-abc123",
        "name": "Past Giveaway",
        "winner": "76561198111111111",
        "winner_name": "WinnerName"
      }
    ]
  }
}

​
My Active Giveaways

GET /giveaways/my

Retrieves active giveaways created by the current user.
GET /giveaways/my
Authentication: connected Response 
{
  "status": "success",
  "data": {
    "list": []
  }
}

​
My Giveaway History

GET /giveaways/history/my

Retrieves past giveaways created by the current user.
GET /giveaways/history/my
Authentication: connected Response 
{
  "status": "success",
  "data": {
    "list": []
  }
}

​
Get Giveaway Details

GET /giveaways/details/:url

Retrieves detailed information about a specific giveaway, including participants and items.
GET /giveaways/details/{url}
Authentication: None Path Parameters
​
url
string
required
The unique URL identifier of the giveaway.
Response 
{
  "status": "success",
  "data": {
    "details": {
      "id": 1,
      "url": "giveaway-abc123",
      "name": "Unusual Hat Giveaway",
      "description": "Win an amazing unusual hat!",
      "description_entered": "Thanks for entering!",
      "creator": "76561198000000000",
      "max_entries": 500,
      "current_entries": 150,
      "private": 0,
      "end_time": 1706832000,
      "items": [
        {
          "id": 1,
          "name": "Unusual Hat",
          "image": "https://...",
          "value": 50000
        }
      ],
      "participants": [
        {
          "steamId": "76561198111111111",
          "name": "ParticipantName",
          "image": "https://..."
        }
      ]
    }
  }
}

​
Get Giveaway Comments

GET /giveaways/comments/:url

Retrieves paginated comments for a specific giveaway.
GET /giveaways/comments/{url}
Authentication: None Path Parameters
​
url
string
required
The unique URL identifier of the giveaway.
Query Parameters
​
page
integer
default:"0"
Page number (0-indexed). 10 comments per page.
Response 
{
  "status": "success",
  "data": {
    "comments": [
      {
        "id": 1,
        "user": "76561198000000000",
        "user_name": "PlayerName",
        "user_image": "https://...",
        "content": "Thanks for the giveaway!",
        "timestamp": 1706745600
      }
    ],
    "count": 25
  }
}

​
Get Joined List

GET /giveaways/joinedList

Retrieves a list of giveaways the current user has joined.
GET /giveaways/joinedList
Authentication: connected Response 
{
  "status": "success",
  "data": {
    "list": [
      {
        "raffle_id": 1,
        "url": "giveaway-abc123"
      }
    ]
  }
}

​
Check If User Joined

GET /giveaways/isIn/:url

Checks if the current user has joined a specific giveaway.
GET /giveaways/isIn/{url}
Authentication: connected Path Parameters
​
url
string
required
The unique URL identifier of the giveaway.
Response 
{
  "status": "success",
  "data": {
    "isIn": true
  }
}

​
Join Giveaway

POST /giveaways/join/:url

Joins a specific giveaway. Validates entry limits and activity status.
POST /giveaways/join/{url}
Authentication: connected Path Parameters
​
url
string
required
The unique URL identifier of the giveaway.
Response 
{
  "status": "success",
  "data": {
    "message": "Successfully joined the raffle"
  }
}
Errors
StatusMessage
errorCannot join this raffle
errorRaffle url is required

​
Leave Giveaway

POST /giveaways/leave/:url

Leaves a specific giveaway the user has previously joined.
POST /giveaways/leave/{url}
Authentication: connected Path Parameters
​
url
string
required
The unique URL identifier of the giveaway.
Response 
{
  "status": "success",
  "data": {
    "message": "Successfully left the raffle"
  }
}

​
Add Comment

POST /giveaways/comment

Adds a comment to a giveaway. Rate limited to one comment per 10 minutes.
POST /giveaways/comment
Authentication: connected Body Parameters
​
url
string
required
The unique URL identifier of the giveaway.
​
comment
string
required
The comment text (max 300 characters).
Response 
{
  "status": "success",
  "data": {
    "message": "Comment successfully added"
  }
}
Errors
StatusMessage
errorComment cannot be empty
errorComment is too long (maximum 300 characters)
errorYou can only post one comment every 10 minutes

​
Delete Comment (Admin)

POST /giveaways/deleteComment/:id

Deletes a comment from a giveaway. Admin only.
POST /giveaways/deleteComment/{id}
Authentication: connected, admin Path Parameters
​
id
integer
required
The comment ID to delete.
Response 
{
  "status": "success",
  "data": {
    "message": "Comment successfully deleted"
  }
}

​
Create Giveaway

POST /giveaways/create

Creates a new giveaway. Rate limited to 1 giveaway per hour. Transfers selected items from the user’s inventory to the giveaway pool.
POST /giveaways/create
Authentication: connected Body Parameters
​
raffle_name
string
required
Name of the giveaway.
​
max_entries
integer
required
Maximum number of participants. Minimum 100 for public, minimum 2 for private giveaways.
​
private
string
required
"0" for public, "1" for private.
​
description
string
required
Description shown before entering the giveaway.
​
description_entered
string
required
Description shown after entering the giveaway.
​
time
string
required
Duration of the giveaway.
​
items
array
required
Array of item IDs from the user’s inventory to include (max 50 items).
​
discord_required
boolean
Whether Discord verification is required to join.
Response 
{
  "status": "success",
  "data": {
    "message": "Giveaway created successfully",
    "url": "giveaway-abc123"
  }
}
Errors
StatusMessage
errorRate limit exceeded. Maximum 1 giveaway per hour
errorInvalid parameters
errorInvalid time duration
errorItems are required
error2FA required
errorItems not found or too many items (max 50)
errorMinimum 100 entries required for public giveaways
errorMinimum 2 entries required for private giveaways