ScopliDrop
Run Discord giveaways from your AI assistant. Create, schedule, end and reroll them, and read entries, winners and analytics through the ScopliDrop API.
Hosted MCP Server
npx add-mcp 'https://t.scoplidrop.com/mcp'Installs into Claude Code, Codex, Cursor and more
Documentation
Read and manage a server's giveaways, entry tasks, coin economy and analytics from your own code. Requests and responses are JSON over HTTPS, and one API key acts on one server.
JSON over HTTPSOne key per serverBusiness plan and up
Overview
One base URL, one key per server
Every request goes to the base URL below and carries an API key. The key decides which server the request acts on.
Base URL
https://t.scoplidrop.com/v1
Conventions
- Paths never contain a server id. The API key selects the server.
- Request and response bodies are JSON, and field names are snake_case.
- Timestamps are ISO 8601 strings in UTC, for example 2027-01-31T18:00:00.000Z.
- Discord ids (servers, channels, roles, members) are strings of 17 to 20 digits. Giveaway, entry and task template ids are UUIDs.
- Unknown body fields and unknown query parameters are rejected with a 400, so a misspelled filter never returns an unfiltered list.
Authentication
Authenticate with an API key
API keys are part of the Business and Enterprise plans. Creating one takes a minute in the dashboard.
- 1 In the ScopliDrop dashboard, open Developer, then API keys and MCP, and create a key. You need the Manage integrations permission on the server.
- 2 Pick the scopes the key needs and when it expires: in 30 days, in 90 days, in 1 year or never.
- 3 Copy the key. It starts with sdrop_ and is shown once. ScopliDrop keeps only a hash of it, so a lost key cannot be recovered. Revoke it and create a new one.
- 4 Send the key on every request as a Bearer token in the Authorization header.
curl "https://t.scoplidrop.com/v1/server" \
-H "Authorization: Bearer sdrop_..."
What a key is tied to
- A key belongs to one server. It cannot read or change any other server.
- A key acts as the member who created it. Every write is checked against that member's permissions on the server at the time of the call, and is recorded in the server's audit log.
- If that member loses a permission, writes that need it fail with forbidden.
- A revoked or expired key stops working at once and answers 401. A server can have up to 10 active keys.
- The server must be on the Business or Enterprise plan when the call is made. Otherwise the API answers plan_required. Compare plans on the ScopliDrop pricing page.
Scopes
Scopes limit what a key can do
Give each key only the scopes it needs. A call without the right scope answers 403 with the code forbidden.
| Scope | Allows |
|---|---|
| giveaways:read | List giveaways and scheduled giveaways, and read one giveaway, its entries and its winners. |
| giveaways:write | Create, schedule and edit giveaways, cancel a schedule, end giveaways and reroll winners. |
| templates:read | List task templates and read one, with the settings of its tasks. |
| templates:write | Create, edit and delete task templates. |
| economy:read | Read coin balances, the leaderboard and the transaction log. |
| economy:write | Add coins to a member's balance or take coins away. |
| analytics:read | Read the analytics overview. |
A refused call names the missing scope in details.required_scope. GET /server, the channel and role lists, the task type endpoints and the feature endpoints need no scope.
{
"error": {
"code": "invalid_request",
"message": "The request is not valid.",
"details": [
{
"path": "end.at",
"message": "Must be an ISO 8601 date with a time zone, for example 2027-01-31T18:00:00Z."
}
]
}
}
- code is stable. Branch on it.
- message is a plain sentence for a person to read. Its wording can change.
- details is optional and depends on the code, as listed below.
| Code | Status | When it happens |
|---|---|---|
| invalid_request | 400 | The body, the query string or an id is not valid. Details list each problem with its path and a message. When the bot lacks Discord permissions in the channel, details.missing_permissions lists them. |
| unauthorized | 401 | The API key is missing, not valid, revoked or expired. |
| forbidden | 403 | The key lacks the scope the endpoint needs, or the member who created the key is not allowed to do this on the server. |
| plan_required | 403 | The server's plan does not include the API or the feature. Details carry current_plan and required_plan, or feature_key for a single feature. |
| not_found | 404 | The resource does not exist on this server, or the path is not a v1 endpoint. |
| conflict | 409 | The action does not fit the current state, for example ending a giveaway that is not running. Also the answer to an idempotency key whose first request is still running or has an unknown outcome. |
| rate_limited | 429 | Too many requests. Wait for the number of seconds in the Retry-After header. |
| server_error | 500 | Something went wrong on our side. After a failed write, read the resource before you retry. |
| upstream_unavailable | 503 | ScopliDrop or Discord could not be reached, and nothing was changed. Send the request again in a moment. |
| outcome_unknown | 502, 504 | A write was sent and its result is not known, so it may have been applied. No answer came back (504 when ScopliDrop stopped waiting for one), the answer was an unexpected failure, or the write was made and could not be read back. Read the resource before you send it again. |
Pagination
Lists are paginated with a cursor
Every list endpoint answers with an object that holds the items of one page in data and the cursor of the next page in next_cursor.
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
- next_cursor is null on the last page.
- Pass a cursor back unchanged. A value the API did not return answers 400.
- Each list has a fixed order, stated on its endpoint.
Request
curl "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001/entries?limit=2" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000010",
"user_id": "200000000000000001",
"username": "example_member",
"entries": 3,
"source": "discord-embed",
"created_at": "2027-01-24T18:05:12.000Z"
},
{
"id": "00000000-0000-4000-8000-000000000011",
"user_id": "200000000000000002",
"username": "another_member",
"entries": 1,
"source": "share-link",
"created_at": "2027-01-24T18:09:40.000Z"
}
],
"next_cursor": "eyJ2IjoxLCJvIjoyfQ"
}
Next page
curl "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001/entries?limit=2&cursor=eyJ2IjoxLCJvIjoyfQ" \
-H "Authorization: Bearer sdrop_..."
Rate limits
Rate limits are counted per API key
Each limit is counted over one minute. A request over a limit answers 429 with the code rate_limited and a Retry-After header that gives the wait in seconds.
| Limit | Counted for |
|---|---|
| 120 requests per minute | Each API key, every request. |
| 20 writes per minute | Each API key, every POST, PATCH and DELETE. A write also counts toward the 120. |
| 300 requests per minute | Each IP address, counted before the key is checked. |
Idempotency
Retry a write safely with an idempotency key
A dropped connection can hide whether a write was made. Send an Idempotency-Key header with the write, and sending it again does not make it twice. Every POST, PATCH and DELETE accepts it.
| Endpoint | What it does |
|---|---|
| POST /giveaways | Create a giveaway |
| PATCH /giveaways/{id} | Update a giveaway |
| POST /giveaways/{id}/end | End a giveaway now |
| POST /giveaways/{id}/reroll | Reroll winners |
| POST /scheduled-giveaways | Schedule a giveaway |
| PATCH /scheduled-giveaways/{id} | Update a scheduled giveaway |
| DELETE /scheduled-giveaways/{id} | Cancel a scheduled giveaway |
| POST /task-templates | Create a task template |
| PATCH /task-templates/{id} | Update a task template |
| DELETE /task-templates/{id} | Delete a task template |
| POST /economy/balances/{user_id}/adjust | Adjust a member's balance |
- The header is optional. Its value is 1 to 255 printable ASCII characters, for example a UUID. Use a new value for each write you intend to make.
- A key is remembered for 24 hours, for one API key, method and path. The same value sent to two endpoints is two keys.
- The same key with the same body answers with the first response again, with the header Idempotency-Replayed: true. The write is not made a second time.
- The same key with a different body answers invalid_request with the status 400. Use a new key for a different request.
- A write that was refused without changing anything frees its key, for example a validation error, a missing permission, a plan limit or a resource that does not exist. Fix the request and send it again with the same key.
- A key whose first request is still running, or ended with outcome_unknown, answers conflict with the status 409 until the key expires. Read the resource to see what happened. If the write is still needed, send it with a new key.
- When ScopliDrop cannot check a key, it does not make the write and answers upstream_unavailable.
Request
curl -X POST "https://t.scoplidrop.com/v1/economy/balances/200000000000000001/adjust" \
-H "Authorization: Bearer sdrop_..." \
-H "Idempotency-Key: 5f0c2a1e-7d43-4b8e-9a6f-2c1d3e4f5a6b" \
-H "Content-Type: application/json" \
-d '{
"amount": 500,
"reason": "Community event prize"
}'
Header on a replayed response
Idempotency-Replayed: true
Server
Check a key and read the server's channels and roles
Call GET /server first. It confirms that a key works and shows the server it acts on, the server's plan and the key's scopes. The channel and role lists give the Discord ids a giveaway takes.
Get the server
GET /server No scope needed
| Field | Type | Description |
|---|---|---|
| id | string | The Discord server id. |
| name | string | null | The server name as the bot last saw it. |
| plan | string | The server's plan. |
| key.id | string | The id of the API key behind the call. |
| key.name | string | The name given to the key in the dashboard. |
| key.scopes | string[] | The scopes the key holds. |
Request
curl "https://t.scoplidrop.com/v1/server" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "100000000000000000",
"name": "Example Server",
"plan": "enterprise",
"key": {
"id": "00000000-0000-4000-8000-0000000000aa",
"name": "Website backend",
"scopes": [
"giveaways:read",
"giveaways:write"
]
}
}
List channels
GET /server/channels No scope needed
The channels of the server in the order the Discord sidebar shows them. Channels outside a category come first, then the channels of each category. Take the channel_id of a new giveaway and announcements.winner_channel_id from here.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| search | string | Only the channels or roles whose name contains this text, 1 to 100 characters. Case, spaces, dashes and emoji are ignored, so staff chat finds staff-chat. |
| type | string | Only the channels of one type: text, announcement, voice, stage or forum. |
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The Discord channel id. |
| name | string | The channel name. |
| type | string | One of text, announcement, voice, stage and forum. A giveaway is announced in a text or announcement channel. |
| category | string | null | The name of the category the channel sits under. Null for a channel outside any category. |
| bot_can_post | boolean | null | Whether the ScopliDrop bot can post a giveaway in the channel. Null when the bot could not be asked just now. |
| missing_permissions | string[] | The Discord permissions the bot lacks to post there, among ViewChannel, SendMessages and EmbedLinks. Empty when the bot can post, and when that is not known. |
Request
curl "https://t.scoplidrop.com/v1/server/channels" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "100000000000000003",
"name": "rules",
"type": "text",
"category": null,
"bot_can_post": false,
"missing_permissions": [
"SendMessages"
]
},
{
"id": "100000000000000001",
"name": "giveaways",
"type": "announcement",
"category": "Community",
"bot_can_post": true,
"missing_permissions": []
},
{
"id": "100000000000000004",
"name": "staff-chat",
"type": "text",
"category": "Staff",
"bot_can_post": true,
"missing_permissions": []
}
],
"next_cursor": null
}
List roles
GET /server/roles No scope needed
The roles of the server, highest first. @everyone and the roles of bots are left out. Take announcements.ping_role_ids and the role ids of role tasks from here.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| search | string | Only the channels or roles whose name contains this text, 1 to 100 characters. Case, spaces, dashes and emoji are ignored, so staff chat finds staff-chat. |
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The Discord role id. |
| name | string | The role name. |
| mentionable | boolean | Whether members can mention the role. |
| managed | boolean | True for a role that Discord or an integration manages, such as the server booster role. It cannot be given to a member. |
Request
curl "https://t.scoplidrop.com/v1/server/roles" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "300000000000000001",
"name": "Moderators",
"mentionable": false,
"managed": false
},
{
"id": "300000000000000002",
"name": "Giveaway Pings",
"mentionable": true,
"managed": false
},
{
"id": "300000000000000003",
"name": "Server Booster",
"mentionable": false,
"managed": true
}
],
"next_cursor": null
}
Giveaways
Create, read and manage giveaways
Read a server's giveaways, create and edit them, end them and reroll their winners.
The giveaway object
Every giveaway endpoint returns this object. Webhook events carry it too.
| Field | Type | Description |
|---|---|---|
| id | string | The giveaway id. |
| status | string | One of active or ended. A giveaway waiting for its start is a scheduled giveaway, read with GET /scheduled-giveaways. |
| prize | string | What the winners get. |
| description | string | null | The description shown under the prize. |
| image_url | string | null | The image of the giveaway. |
| winner_count | integer | How many winners are drawn. |
| starts_at | string | When the giveaway starts. |
| ends_at | string | null | When the giveaway ends, or the moment it ended. Null while it runs with no end date. |
| end_condition | object | How the giveaway ends. See the table below. |
| channel_id | string | The Discord channel the giveaway is announced in. |
| message_id | string | null | The Discord announcement message. Null until the bot has posted it. |
| url | string | null | The public giveaway page. |
| entries_count | integer | Total entries in the draw. One member can hold several. |
| participants_count | integer | How many members have entered. |
| requirements.minimum_account_age_days | integer | Minimum age of the Discord account in days. 0 means no minimum. |
| requirements.require_2fa | boolean | Whether members who enter through the giveaway page need two-factor authentication on their Discord account. |
| announcements.winner_channel_id | string | null | The channel for the winner announcement. Null means the giveaway's own channel. |
| announcements.ping_role_ids | string[] | The roles pinged in the giveaway's Discord posts. |
| tasks | object[] | The entry tasks. Each has type, name, required and points. The settings of a task are never returned here. A task template returns them. |
| winners | object[] | null | Null until the giveaway has ended. Then one object per winner in draw order, with position (starting at 1), user_id and prize. |
| created_at | string | When the giveaway was created. |
End conditions
| end_condition | Meaning |
|---|---|
| { "type": "time" } | Ends at ends_at. |
| { "type": "participants", "count": 500 } | Ends as soon as count members have entered. |
| { "type": "member_goal", "count": 10000, "reached": false } | Ends when the server reaches count members. If ends_at comes first, nobody wins. |
| { "type": "manual", "label": "When we hit 1,000 boosts" } | Ends when a host ends it. label is the text shown instead of a date. |
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 128,
"participants_count": 97,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
}
List giveaways
GET /giveaways Scope giveaways:read
Giveaways come newest first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| status | string | Only giveaways with this status: active or ended. Giveaways waiting for their start are listed by GET /scheduled-giveaways. |
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Request
curl "https://t.scoplidrop.com/v1/giveaways?status=active" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 128,
"participants_count": 97,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
}
],
"next_cursor": null
}
Get a giveaway
GET /giveaways/{id} Scope giveaways:read
An id that belongs to another server answers 404, like an id that does not exist.
Request
curl "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 128,
"participants_count": 97,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
}
Create a giveaway
POST /giveaways Scope giveaways:write
Creating a giveaway announces it in the Discord channel immediately. There is no draft step. To post it at a later time, or on a repeating rule, schedule the giveaway instead.
- A successful call answers 201 with the new giveaway.
- If the bot lacks Discord permissions in the channel, nothing is created and the call answers invalid_request with details.missing_permissions.
- Leave out both tasks and task_template_ids for a giveaway anyone can enter in one click. The task types and their settings are listed under Tasks and task types.
- ScopliDrop validates the request the same way it validates a giveaway built in the dashboard. A refusal comes back as invalid_request with the field it is about.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| prize | string | Yes | What the winners get. 1 to 150 characters. |
| channel_id | string | Yes | The Discord channel the giveaway is announced in. |
| end | object | Yes | How the giveaway ends. See the table below. |
| description | string | No | Up to 500 characters. |
| image | object | No | An object with url and an optional placement. The placement is embed (inside the announcement, the default) or separate_message (posted above it). |
| winner_count | integer | No | 1 to 10,000. Defaults to 1. |
| announcements.winner_channel_id | string | No | The channel for the winner announcement. Defaults to the giveaway's channel. |
| announcements.ping_role_ids | string[] | No | The roles to ping in the giveaway's Discord posts. |
| requirements.minimum_account_age_days | integer | No | Minimum age of the Discord account in days, 0 to 365. Defaults to 0. |
| requirements.require_2fa | boolean | No | Whether members who enter through the giveaway page need two-factor authentication on their Discord account. Defaults to false. |
| tasks | object[] | No | Entry tasks, at least one when present. Each task has type (required, a type from the task type list, for example youtube-subscribe), config (the settings of that task type, laid over its defaults), name (defaults to the name of the task type), required (defaults to false) and points (a whole number from 1 to 20, defaults to 1). |
| task_template_ids | string[] | No | 1 to 11 ids of task templates, from the task template list. Their tasks are merged in order. Cannot be combined with tasks. |
The end object
| end | Meaning |
|---|---|
| { "type": "time", "at": "2027-01-31T18:00:00Z" } | Ends on a date. at is an ISO 8601 date with a time zone. |
| { "type": "participants", "count": 500 } | Ends as soon as count members have entered. count is 1 to 100,000. |
| { "type": "member_goal", "count": 10000, "at": "2027-06-30T18:00:00Z" } | Ends when the server reaches count members (2 to 50,000,000). at is optional on create. Without it the giveaway waits for the goal for up to 365 days. |
| { "type": "manual", "label": "When we hit 1,000 boosts" } | Ends when a host ends it. label is the text shown instead of a date, 1 to 100 characters. |
Request
curl -X POST "https://t.scoplidrop.com/v1/giveaways" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1,
"end": {
"type": "time",
"at": "2027-01-31T18:00:00Z"
},
"requirements": {
"minimum_account_age_days": 30
}
}'
Response
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": null,
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 0,
"participants_count": 0,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
}
Update a giveaway
PATCH /giveaways/{id} Scope giveaways:write
Send only the fields to change, and at least one.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| description | string | No | Up to 500 characters. |
| image | object | null | No | Same object as on create. null removes the image. |
| winner_count | integer | No | 1 to 10,000. |
| end | object | No | Replaces the end condition as a whole. Same shapes as on create, except that member_goal must name its date in at. |
| announcements.winner_channel_id | string | null | No | The channel for the winner announcement. null goes back to the giveaway's own channel. |
| announcements.ping_role_ids | string[] | No | The roles to ping in the giveaway's Discord posts. |
| add_tasks | object[] | No | Tasks to append. Each task has type, config, name and points, as on create. required is not accepted, because a task added to a giveaway that already exists is always optional. A running giveaway that was created without tasks cannot get tasks later. |
| notify_participants | boolean | No | Whether the bot tells current participants about the added tasks. Defaults to true. Only valid together with add_tasks. |
What cannot be changed after creation
- prize
- channel_id. Moving the announcement to another channel is done in the dashboard.
- requirements (minimum account age and two-factor authentication)
- The tasks a giveaway already has. They cannot be edited or removed, and task_template_ids is create only. New tasks go in add_tasks.
- The start. A giveaway created through the API starts at once.
Sending one of these fields answers 400.
Request
curl -X PATCH "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"winner_count": 3,
"end": {
"type": "time",
"at": "2027-02-07T18:00:00Z"
}
}'
Response
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "active",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 3,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-02-07T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 128,
"participants_count": 97,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": null,
"created_at": "2027-01-24T18:00:00.000Z"
}
End a giveaway now
POST /giveaways/{id}/end Scope giveaways:write
Ends a running giveaway immediately and draws its winners. The request has no body. Only a giveaway with the status active can be ended. Any other status answers conflict.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Request
curl -X POST "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001/end" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "00000000-0000-4000-8000-000000000001",
"status": "ended",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-28T09:30:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 412,
"participants_count": 305,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": [
{
"position": 1,
"user_id": "200000000000000001",
"prize": "Discord Nitro (1 month)"
}
],
"created_at": "2027-01-24T18:00:00.000Z"
}
Reroll winners
POST /giveaways/{id}/reroll Scope giveaways:write
Draws winners again on an ended giveaway. Any other status answers conflict. The body is optional.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| user_ids | string[] | No | The Discord ids of the winners to replace. Leave it out to draw every winner again. |
Response fields
| Field | Type | Description |
|---|---|---|
| giveaway | object | The giveaway with its new winners. |
| previous_winners | string[] | The Discord ids of the winners before the reroll, in draw order. |
Request
curl -X POST "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001/reroll" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"user_ids": [
"200000000000000001"
]
}'
Response
{
"giveaway": {
"id": "00000000-0000-4000-8000-000000000001",
"status": "ended",
"prize": "Discord Nitro (1 month)",
"description": "One month of Nitro for one member.",
"image_url": null,
"winner_count": 1,
"starts_at": "2027-01-24T18:00:00.000Z",
"ends_at": "2027-01-31T18:00:00.000Z",
"end_condition": {
"type": "time"
},
"channel_id": "100000000000000001",
"message_id": "100000000000000002",
"url": "https://www.scoplidrop.com/g/EXAMPLE",
"entries_count": 412,
"participants_count": 305,
"requirements": {
"minimum_account_age_days": 30,
"require_2fa": false
},
"announcements": {
"winner_channel_id": null,
"ping_role_ids": []
},
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1
}
],
"winners": [
{
"position": 1,
"user_id": "200000000000000002",
"prize": "Discord Nitro (1 month)"
}
],
"created_at": "2027-01-24T18:00:00.000Z"
},
"previous_winners": [
"200000000000000001"
]
}
List entries
GET /giveaways/{id}/entries Scope giveaways:read
Entries come in the order members entered, oldest first, so pages stay put while new entries arrive.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The entry id. |
| user_id | string | The member's Discord id. |
| username | string | null | The Discord username the member entered under. |
| entries | integer | How many entries this member holds in the draw. |
| source | string | null | Where the member entered from, for example discord-embed or share-link. |
| created_at | string | When the member entered. |
An entry carries nothing else about the member. IP addresses, device data, emails, countries and fraud checks stay out of the API.
Request
curl "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001/entries" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000010",
"user_id": "200000000000000001",
"username": "example_member",
"entries": 3,
"source": "discord-embed",
"created_at": "2027-01-24T18:05:12.000Z"
},
{
"id": "00000000-0000-4000-8000-000000000011",
"user_id": "200000000000000002",
"username": "another_member",
"entries": 1,
"source": "share-link",
"created_at": "2027-01-24T18:09:40.000Z"
}
],
"next_cursor": null
}
List winners
GET /giveaways/{id}/winners Scope giveaways:read
Winners come in draw order. The list is empty until the giveaway has ended.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| position | integer | The draw position, starting at 1. |
| user_id | string | The winner's Discord id. |
| prize | string | What this position wins. |
| username | string | null | The Discord username the winner entered under. |
Request
curl "https://t.scoplidrop.com/v1/giveaways/00000000-0000-4000-8000-000000000001/winners" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"position": 1,
"user_id": "200000000000000001",
"prize": "Discord Nitro (1 month)",
"username": "example_member"
}
],
"next_cursor": null
}
Scheduled giveaways
Schedule a giveaway or a recurring series
Save a giveaway now and let ScopliDrop post it later, once or on a repeating rule. These are the schedules of the dashboard's Scheduled tab, so a schedule made through the API shows there and can be edited from either side.
The scheduled giveaway object
Every scheduled giveaway endpoint returns this object. A one-time schedule posts one giveaway. A series posts a new giveaway on each run of its rule.
| Field | Type | Description |
|---|---|---|
| id | string | The id of the schedule. |
| name | string | The name shown in the dashboard. Defaults to the prize. |
| status | string | Where the schedule stands. See the table below. |
| starts_at | string | When the giveaway is posted. For a series, when its first run is posted. |
| next_run_at | string | null | When the next giveaway is posted. Null when nothing is left to post. |
| end | object | How each giveaway it posts ends, in the shape it was sent. |
| recurrence | object | null | The rule of a series as it was sent, with its defaults filled in, plus run_count, the number of giveaways it has posted so far. Null for a one-time schedule. |
| giveaway | object | What it posts, in short. An object with prize, channel_id and winner_count. |
| launched_giveaway_id | string | null | The id of the giveaway it posted, to read with the giveaway endpoints. Null until a giveaway has been posted. |
| error | string | null | Why the giveaway could not be posted, when the status is failed. Null otherwise. |
| created_at | string | When the schedule was created. |
Statuses
| status | Meaning |
|---|---|
| pending | A one-time schedule waiting for its start. |
| launched | A one-time schedule whose giveaway has been posted. |
| failed | A one-time schedule whose giveaway could not be posted. The error field says why. |
| recurring | A running series. It posts a giveaway on each run of its rule. |
| paused | A series on pause. It posts nothing until it is resumed. |
| ended | A series that ran out of runs or passed its ends_at. It posts nothing more and cannot be resumed. |
{
"id": "00000000-0000-4000-8000-000000000030",
"name": "Friday Nitro drop",
"status": "recurring",
"starts_at": "2027-01-29T17:00:00.000Z",
"next_run_at": "2027-01-29T17:00:00.000Z",
"end": {
"type": "duration",
"minutes": 2880
},
"recurrence": {
"frequency": "weekly",
"days_of_week": [
"fri"
],
"time": "18:00",
"timezone": "Europe/Paris",
"interval": 1,
"day_of_month": null,
"ends_at": null,
"max_runs": null,
"run_count": 0
},
"giveaway": {
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1
},
"launched_giveaway_id": null,
"error": null,
"created_at": "2027-01-25T10:00:00.000Z"
}
List scheduled giveaways
GET /scheduled-giveaways Scope giveaways:read
The schedules of the server, the next one to be posted first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| status | string | Only schedules with this status: pending, launched, failed, recurring, paused or ended. |
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Request
curl "https://t.scoplidrop.com/v1/scheduled-giveaways?status=recurring" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000030",
"name": "Friday Nitro drop",
"status": "recurring",
"starts_at": "2027-01-29T17:00:00.000Z",
"next_run_at": "2027-01-29T17:00:00.000Z",
"end": {
"type": "duration",
"minutes": 2880
},
"recurrence": {
"frequency": "weekly",
"days_of_week": [
"fri"
],
"time": "18:00",
"timezone": "Europe/Paris",
"interval": 1,
"day_of_month": null,
"ends_at": null,
"max_runs": null,
"run_count": 0
},
"giveaway": {
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1
},
"launched_giveaway_id": null,
"error": null,
"created_at": "2027-01-25T10:00:00.000Z"
}
],
"next_cursor": null
}
Get a scheduled giveaway
GET /scheduled-giveaways/{id} Scope giveaways:read
An id that belongs to another server answers 404, like an id that does not exist.
Request
curl "https://t.scoplidrop.com/v1/scheduled-giveaways/00000000-0000-4000-8000-000000000030" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "00000000-0000-4000-8000-000000000030",
"name": "Friday Nitro drop",
"status": "recurring",
"starts_at": "2027-01-29T17:00:00.000Z",
"next_run_at": "2027-01-29T17:00:00.000Z",
"end": {
"type": "duration",
"minutes": 2880
},
"recurrence": {
"frequency": "weekly",
"days_of_week": [
"fri"
],
"time": "18:00",
"timezone": "Europe/Paris",
"interval": 1,
"day_of_month": null,
"ends_at": null,
"max_runs": null,
"run_count": 0
},
"giveaway": {
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1
},
"launched_giveaway_id": null,
"error": null,
"created_at": "2027-01-25T10:00:00.000Z"
}
Schedule a giveaway
POST /scheduled-giveaways Scope giveaways:write
Scheduling a giveaway posts nothing now. The giveaway is announced in the Discord channel at its start time, and each run of a series is announced at its own time. Until then the schedule can be changed or cancelled.
- A successful call answers 201 with the new scheduled giveaway.
- Leave out recurrence for a one-time giveaway. starts_at is then required.
- Send recurrence for a series. Each run posts a new giveaway that stays open for the duration in end, the only end a series accepts. Without starts_at, the first run is the next time the rule falls on.
- Scheduling follows the limits of the server's plan, as in the dashboard. They cap how many giveaways can wait at once, how far ahead one can start and how many series can run. A call past a limit is refused with the dashboard's message, and nothing is saved.
- The member who created the key needs the permission to schedule giveaways on the server. The giveaway itself is validated the way a new giveaway is, so a refusal comes back as invalid_request with the field it is about.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
A schedule takes the body fields of Create a giveaway, such as prize, channel_id and tasks, with its own end. It adds the fields below.
| Field | Type | Required | Description |
|---|---|---|---|
| starts_at | string | No | When the giveaway is posted, an ISO 8601 date in the future with a time zone. Required without recurrence. For a series it is the earliest date the series may start, and its first run is the first time the rule falls on or after it. Without it the series starts at the next run of its rule. |
| end | object | Yes | How each giveaway ends. See the table below. A series takes duration only. |
| recurrence | object | No | The rule of a series. See the table below. Leave it out for a one-time giveaway. |
| name | string | No | The name shown in the dashboard, 50 characters at most. Defaults to the prize. |
The end object of a schedule
| end | Meaning |
|---|---|
| { "type": "duration", "minutes": 2880 } | Ends minutes after the giveaway is posted. 2880 minutes is 48 hours. The only end a series accepts. |
| { "type": "participants", "count": 500 } | Ends as soon as count members have entered. |
| { "type": "member_goal", "count": 10000, "minutes": 10080 } | Ends when the server reaches count members. minutes is optional and sets a deadline after the giveaway is posted. If the deadline comes first, nobody wins. |
| { "type": "manual", "label": "When we hit 1,000 boosts" } | Ends when a host ends it. label is the text shown instead of a date, 1 to 100 characters. |
The recurrence object
| Field | Type | Required | Description |
|---|---|---|---|
| frequency | string | Yes | One of daily, weekly and monthly. |
| time | string | Yes | The time of each run, written HH:MM on a 24 hour clock, in timezone. |
| timezone | string | Yes | An IANA time zone, for example Europe/Paris. Runs keep their local time when the clocks change. |
| interval | integer | No | Run every how many days, weeks or months, 1 to 52. Defaults to 1. |
| days_of_week | string[] | No | The days a weekly series runs on, at least one, among mon, tue, wed, thu, fri, sat and sun. Weekly only. |
| day_of_month | integer | No | The day a monthly series runs on, 1 to 31. In a shorter month, a day past its end runs on the month's last day. Monthly only. |
| ends_at | string | No | No run starts after this date, an ISO 8601 date with a time zone. Leave it out for a series with no end date. |
| max_runs | integer | No | The series stops after this many runs, 1 to 1,000. Leave it out for no limit. |
The request below starts a weekly series. Every Friday at 18:00 Paris time, it posts a giveaway that stays open for 48 hours.
Request
curl -X POST "https://t.scoplidrop.com/v1/scheduled-giveaways" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Friday Nitro drop",
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1,
"end": {
"type": "duration",
"minutes": 2880
},
"recurrence": {
"frequency": "weekly",
"days_of_week": [
"fri"
],
"time": "18:00",
"timezone": "Europe/Paris"
}
}'
Response
{
"id": "00000000-0000-4000-8000-000000000030",
"name": "Friday Nitro drop",
"status": "recurring",
"starts_at": "2027-01-29T17:00:00.000Z",
"next_run_at": "2027-01-29T17:00:00.000Z",
"end": {
"type": "duration",
"minutes": 2880
},
"recurrence": {
"frequency": "weekly",
"days_of_week": [
"fri"
],
"time": "18:00",
"timezone": "Europe/Paris",
"interval": 1,
"day_of_month": null,
"ends_at": null,
"max_runs": null,
"run_count": 0
},
"giveaway": {
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1
},
"launched_giveaway_id": null,
"error": null,
"created_at": "2027-01-25T10:00:00.000Z"
}
Update a scheduled giveaway
PATCH /scheduled-giveaways/{id} Scope giveaways:write
Send only the fields to change, and at least one. Changes apply to the giveaways posted from now on. A giveaway already posted keeps running as it is. A schedule that is launched, failed or being posted at that moment answers conflict.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | No | A new name, 50 characters at most. |
| starts_at | string | No | A new start in the future. For a series, when its next run is posted. |
| end | object | No | Replaces the end as a whole. Same shapes as on create, and a series keeps a duration. |
| recurrence | object | No | Replaces the rule of a series as a whole. Same object as on create. |
| paused | boolean | No | true pauses a series and false resumes it. Sent on a one-time schedule, it answers invalid_request. |
What cannot be changed here
The giveaway a schedule posts, such as prize, channel_id, tasks and task_template_ids. To change them, cancel the schedule and schedule the giveaway again. Sending one of these fields answers 400.
Request
curl -X PATCH "https://t.scoplidrop.com/v1/scheduled-giveaways/00000000-0000-4000-8000-000000000030" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"paused": true
}'
Response
{
"id": "00000000-0000-4000-8000-000000000030",
"name": "Friday Nitro drop",
"status": "paused",
"starts_at": "2027-01-29T17:00:00.000Z",
"next_run_at": "2027-01-29T17:00:00.000Z",
"end": {
"type": "duration",
"minutes": 2880
},
"recurrence": {
"frequency": "weekly",
"days_of_week": [
"fri"
],
"time": "18:00",
"timezone": "Europe/Paris",
"interval": 1,
"day_of_month": null,
"ends_at": null,
"max_runs": null,
"run_count": 0
},
"giveaway": {
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"winner_count": 1
},
"launched_giveaway_id": null,
"error": null,
"created_at": "2027-01-25T10:00:00.000Z"
}
Cancel a scheduled giveaway
DELETE /scheduled-giveaways/{id} Scope giveaways:write
Cancels a one-time schedule before its giveaway is posted, or stops a series so it posts nothing more. A launched or failed schedule is removed from the list. A giveaway already posted from it is never touched and keeps running. The request has no body. A schedule whose giveaway is being posted at that moment answers conflict.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Request
curl -X DELETE "https://t.scoplidrop.com/v1/scheduled-giveaways/00000000-0000-4000-8000-000000000030" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "00000000-0000-4000-8000-000000000030",
"deleted": true
}
Tasks
Entry tasks and the settings each type takes
A task is something a member does to enter, such as following a channel or joining a server. Every task has a type, and each type takes its own settings. The task type endpoints list them all.
How a task is written
The same object is used wherever tasks are sent. That is tasks when a giveaway is created, add_tasks when one is edited, and tasks of a task template.
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | The task type, a type from the task type list, for example youtube-subscribe. |
| config | object | No | The settings of that task type. Send only the settings you want to set. They are laid over the defaults of the type. |
| name | string | No | The name members see. Defaults to the name of the task type. |
| required | boolean | No | Whether a member must complete the task to enter. Defaults to false. Not accepted in add_tasks. |
| points | integer | No | The entries the task is worth, a whole number from 1 to 20. Defaults to 1. |
A task
{
"type": "youtube-subscribe",
"config": {
"url": "https://youtube.com/@scoplidrop",
"verificationMethod": "timer-based"
},
"required": true,
"points": 1
}
What ScopliDrop checks
- A type that is not in the task type list is refused. A setting of the wrong kind is refused too, for example a number sent as a string.
- Settings are validated the way the dashboard validates them. A refusal answers invalid_request, and details names the task and the setting, for example Task 1 (youtube-subscribe): Channel URL is required (config.url).
- A setting marked required in its task type has no default, so it must be sent. On most types that is the link of the task and verificationMethod.
- Some task types and some values need a higher plan. The task type says which in plan, and a refusal answers plan_required.
- A giveaway returns its tasks without their settings. A task template returns them with their settings.
List task types
GET /task-types No scope needed
Returns every task type in one answer, in the list shape. The catalog is short and fixed, so next_cursor is always null. It is the same for every server.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| category | string | Only the task types of one category. One of social, discord, community, web, music, games, roblox, custom. |
The task type object
| Field | Type | Description |
|---|---|---|
| type | string | What goes in the type of a task. |
| name | string | The name of the task type. It is the default name of a task. |
| category | string | The category id, for example social or discord. |
| category_name | string | The category as the dashboard names it. |
| description | string | What the task asks of a member. |
| plan | string | The lowest plan of the server that can use this task type. One of free, premium, business and enterprise. |
| notes | string[] | Things to know that are not a setting, for example that the server needs Leveling turned on. |
| config_fields | object[] | The settings a task of this type takes, in the order of the dashboard. |
| default_config | object | What config starts from. The values you send are laid over it. |
The config field object
One entry of config_fields. Everything after required is only present when it applies.
| Field | Type | Description |
|---|---|---|
| key | string | The key inside config. |
| type | string | How the value is written. One of string, url, number, boolean, enum, string[], object and object[]. |
| label | string | The name of the setting in the dashboard. |
| description | string | What the setting does. |
| required | boolean | True when the task type has no default for it, so a task must send it. |
| default | any | What the setting holds when it is left out. |
| options | object[] | The allowed values of an enum. Each has value and label, and plan when that value needs a higher plan than the task type. |
| example | string | An example value. |
| pattern | string | A regular expression the value must match. |
| min, max | number | The bounds of a number. |
| max_length | integer | The longest text allowed, in characters. |
| max_items | integer | The most items a list may hold. |
| premium | boolean | True when values other than the default need the Premium plan. |
| shown_when | object[] | The setting only applies when each listed setting holds one of the listed values. A condition on a setting that itself does not apply is skipped. Each entry has field and in. |
Request
curl "https://t.scoplidrop.com/v1/task-types?category=web" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"type": "website-visit",
"name": "Visit website",
"category": "web",
"category_name": "Email & Web",
"description": "Visit a specific website or webpage",
"plan": "free",
"notes": [],
"config_fields": [
{
"key": "url",
"type": "url",
"label": "Website URL",
"description": "Full URL to the website",
"required": true,
"example": "https://example.com/page",
"pattern": "^https?:\\/\\/.+\\..+"
},
{
"key": "customNote",
"type": "string",
"label": "Custom Note (Optional)",
"description": "Optional instructions or hints for users",
"required": false,
"max_length": 250
}
],
"default_config": {
"url": "",
"customNote": "",
"verificationMethod": "timer-based"
}
},
{
"type": "collect-email",
"name": "Provide Email",
"category": "web",
"category_name": "Email & Web",
"description": "Collect participant email address",
"plan": "premium",
"notes": [],
"config_fields": [
{
"key": "customNote",
"type": "string",
"label": "Instructions (Optional)",
"description": "Explain why you need this email and how it will be used",
"required": false,
"max_length": 250
}
],
"default_config": {
"customNote": "",
"verificationMethod": "direct-data-collection"
}
}
],
"next_cursor": null
}
Get a task type
GET /task-types/{type} No scope needed
Returns one task type. An unknown type answers not_found.
Request
curl "https://t.scoplidrop.com/v1/task-types/website-visit" \
-H "Authorization: Bearer sdrop_..."
Response
{
"type": "website-visit",
"name": "Visit website",
"category": "web",
"category_name": "Email & Web",
"description": "Visit a specific website or webpage",
"plan": "free",
"notes": [],
"config_fields": [
{
"key": "url",
"type": "url",
"label": "Website URL",
"description": "Full URL to the website",
"required": true,
"example": "https://example.com/page",
"pattern": "^https?:\\/\\/.+\\..+"
},
{
"key": "customNote",
"type": "string",
"label": "Custom Note (Optional)",
"description": "Optional instructions or hints for users",
"required": false,
"max_length": 250
}
],
"default_config": {
"url": "",
"customNote": "",
"verificationMethod": "timer-based"
}
}
Every task type
The task types available today. A config key in bold has no default and must be sent. Call the task type endpoint for the allowed values of each key.
| Type | Name | Plan | Config keys |
|---|---|---|---|
| youtube-subscribe | Follow on YouTube | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| youtube-like | Like YouTube video | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| youtube-comment | Comment YouTube video | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| discord-join | Join Discord Server | free | serverId, inviteUrl, verificationMethod |
| x-follow | Follow on X | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| x-like | Like X post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| x-repost | Repost on X | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| x-comment | Comment X post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| x-post | Post on X | premium | postText, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| instagram-follow | Follow on Instagram | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| instagram-like | Like Instagram post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| instagram-comment | Comment Instagram post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| instagram-repost | Repost in Instagram story | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| instagram-tag-friends | Tag friends in IG comment | free | url, friendCount, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| facebook-follow | Follow on Facebook | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| facebook-join-group | Join Facebook group | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| facebook-like-post | Like Facebook post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| facebook-comment | Comment Facebook post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| facebook-watch | Watch Facebook video | free | url, minTime, verificationMethod, videoCodes |
| twitch-follow | Follow on Twitch | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| twitch-subscribe | Subscribe on Twitch | free | url, minTier, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| discord-role-check | Have Discord Role | free | roleIds, customNote |
| discord-role-assign | Claim Discord Role | free | roleId, customNote |
| discord-voice-time | Voice Channel Activity | free | minValue, aggregationMode, timeWindowDays |
| discord-message-count | Message Activity | free | minValue, aggregationMode, timeWindowDays |
| discord-xp-level | Reach XP/Level | free | requirementType, minValue |
| discord-member-since | Time in Server | premium | memberSinceMode, minMemberDays |
| scoplidrop-giveaway-regular | Giveaway Regular | free | minGiveaways, timeWindowDays |
| scoplidrop-play-minigames | Play Minigames | free | minGames, gameType, timeWindow, minOpponents |
| website-visit | Visit website | free | url, customNote |
| collect-email | Provide Email | premium | customNote |
| tiktok-follow | Follow on TikTok | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| tiktok-like | Like TikTok video | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| tiktok-comment | Comment TikTok video | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| tiktok-repost | Repost TikTok video | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| telegram-join-group | Join Telegram group | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| telegram-view-post | View Telegram post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| kick-follow | Follow on Kick | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| kick-subscribe | Subscribe on Kick | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| kick-watch | Watch Kick stream | free | url, minTime, verificationMethod, videoCodes |
| pinterest-follow | Follow on Pinterest | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| pinterest-visit | Visit Pinterest page | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| reddit-visit-subreddit | Visit subreddit | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| reddit-follow-subreddit | Follow subreddit | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| reddit-follow-user | Follow Reddit user | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| spotify-follow-artist | Follow Spotify artist | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| spotify-follow-playlist | Follow Spotify playlist | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| spotify-listen-song | Listen to Spotify song | free | url, minTime, verificationMethod |
| spotify-save-song | Save Spotify song | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| spotify-pre-save | Pre-save on Spotify | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| bluesky-follow | Follow on Bluesky | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| bluesky-like | Like Bluesky post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| bluesky-repost | Repost on Bluesky | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| snapchat-follow | Follow on Snapchat | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| linkedin-follow-company | Follow LinkedIn company | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| linkedin-follow-user | Follow LinkedIn user | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| linkedin-connect-user | Connect to LinkedIn user | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| youtube-watch | Watch YouTube video | free | url, minTime, verificationMethod, videoCodes |
| tiktok-watch | Watch TikTok video | free | url, minTime, verificationMethod, videoCodes |
| twitch-watch | Watch Twitch stream | free | url, minTime, verificationMethod, videoCodes |
| instagram-watch | Watch Instagram Reel | free | url, minTime, verificationMethod, videoCodes |
| scoplidrop-topgg-upvote | Upvote ScopliDrop on Top.gg | free | None |
| scoplidrop-lootbox-open | Open the lootbox | free | None |
| scoplidrop-listing-upvote | Upvote this giveaway on ScopliDrop | free | None |
| soundcloud-listen-song | Listen to SoundCloud song | free | url, minTime, verificationMethod |
| soundcloud-like-song | Like SoundCloud song | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| soundcloud-repost-song | Repost SoundCloud song | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| soundcloud-follow-artist | Follow SoundCloud artist | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| patreon-visit | Visit Patreon page | free | url |
| meta-quest-wishlist | Add to Meta Wishlist | free | url, verificationMethod |
| steam-wishlist | Wishlist on Steam | premium | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| steam-follow-game | Follow a game on Steam | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| steam-join-group | Join a Steam group | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| roblox-join-community | Join a Roblox Community | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions, minRank, minAccountAgeDays |
| roblox-feature-community | Feature a Roblox Community on Your Profile | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions, minAccountAgeDays |
| roblox-badge | Earn a Roblox Badge | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions, badgeWindow, minAccountAgeDays |
| roblox-own-item | Own a Roblox Game Pass or Item | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions, extraItems, minAccountAgeDays |
| roblox-profile-text | Add Text to Your Roblox Profile | free | profileText, profilePlace, verificationMethod, proofType, screenshotCount, screenshotInstructions, minAccountAgeDays |
| roblox-forum-comment | Comment on a Roblox Forum Post | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions, commentWindow, minAccountAgeDays |
| roblox-play-game | Play a Roblox Game | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| roblox-follow-game | Follow a Roblox Game | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| roblox-favorite-game | Favorite a Roblox Game | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| roblox-like-game | Like a Roblox Game | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| roblox-follow-user | Follow on Roblox | free | url, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| discord-primary-guild | Set Discord Server Tag | premium | serverId, serverName, verificationMethod |
| combo-task | Combo Task | premium | platform, actions, url, minTime, verificationMethod, proofType, screenshotCount, screenshotInstructions |
| custom-task | Custom Task | business | customName, iconId, customNote, verificationMethod, proofType, screenshotCount, screenshotInstructions, taskUrl, verifiedAction, customFields |
Task templates
Save a set of tasks and reuse it
A task template is a named list of tasks a server keeps, the task templates of the dashboard. Create one once, then pass its id in task_template_ids when you create a giveaway.
The task template object
| Field | Type | Description |
|---|---|---|
| id | string | The id of the template. It is what task_template_ids takes. |
| name | string | The name of the template. |
| description | string | null | What the template is for. |
| tasks | object[] | The tasks in order. Each has type, name, required, points and config, the settings of the task. |
| created_at | string | null | When the template was created. |
| updated_at | string | null | When the template was last changed. |
{
"id": "00000000-0000-4000-8000-000000000020",
"name": "Launch tasks",
"description": "Follow us and visit the site",
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1,
"config": {
"url": "https://youtube.com/@scoplidrop",
"proofType": "text",
"screenshotCount": "1",
"verificationMethod": "timer-based"
}
},
{
"type": "website-visit",
"name": "Visit website",
"required": false,
"points": 1,
"config": {
"url": "https://www.scoplidrop.com",
"customNote": "",
"verificationMethod": "timer-based"
}
}
],
"created_at": "2027-01-20T10:00:00.000Z",
"updated_at": "2027-01-20T10:00:00.000Z"
}
List task templates
GET /task-templates Scope templates:read
Returns the task templates of the server, newest first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Request
curl "https://t.scoplidrop.com/v1/task-templates" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000020",
"name": "Launch tasks",
"description": "Follow us and visit the site",
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1,
"config": {
"url": "https://youtube.com/@scoplidrop",
"proofType": "text",
"screenshotCount": "1",
"verificationMethod": "timer-based"
}
},
{
"type": "website-visit",
"name": "Visit website",
"required": false,
"points": 1,
"config": {
"url": "https://www.scoplidrop.com",
"customNote": "",
"verificationMethod": "timer-based"
}
}
],
"created_at": "2027-01-20T10:00:00.000Z",
"updated_at": "2027-01-20T10:00:00.000Z"
}
],
"next_cursor": null
}
Get a task template
GET /task-templates/{id} Scope templates:read
Returns one task template. A template of another server answers not_found.
Request
curl "https://t.scoplidrop.com/v1/task-templates/00000000-0000-4000-8000-000000000020" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "00000000-0000-4000-8000-000000000020",
"name": "Launch tasks",
"description": "Follow us and visit the site",
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1,
"config": {
"url": "https://youtube.com/@scoplidrop",
"proofType": "text",
"screenshotCount": "1",
"verificationMethod": "timer-based"
}
},
{
"type": "website-visit",
"name": "Visit website",
"required": false,
"points": 1,
"config": {
"url": "https://www.scoplidrop.com",
"customNote": "",
"verificationMethod": "timer-based"
}
}
],
"created_at": "2027-01-20T10:00:00.000Z",
"updated_at": "2027-01-20T10:00:00.000Z"
}
Create a task template
POST /task-templates Scope templates:write
- A successful call answers 201 with the new template. Nothing is posted in Discord.
- Every task is validated before the template is saved, so a template saved through the API can always be launched.
- The member who owns the key needs the permission to create templates on the server.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | The name of the template, 25 characters at most. |
| tasks | object[] | Yes | The tasks, at least one, in the order members see them. Each is written as described under how a task is written. |
| description | string | No | What the template is for, 60 characters at most. |
Request
curl -X POST "https://t.scoplidrop.com/v1/task-templates" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Launch tasks",
"description": "Follow us and visit the site",
"tasks": [
{
"type": "youtube-subscribe",
"config": {
"url": "https://youtube.com/@scoplidrop",
"verificationMethod": "timer-based"
},
"required": true
},
{
"type": "website-visit",
"config": {
"url": "https://www.scoplidrop.com"
}
}
]
}'
Response
{
"id": "00000000-0000-4000-8000-000000000020",
"name": "Launch tasks",
"description": "Follow us and visit the site",
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1,
"config": {
"url": "https://youtube.com/@scoplidrop",
"proofType": "text",
"screenshotCount": "1",
"verificationMethod": "timer-based"
}
},
{
"type": "website-visit",
"name": "Visit website",
"required": false,
"points": 1,
"config": {
"url": "https://www.scoplidrop.com",
"customNote": "",
"verificationMethod": "timer-based"
}
}
],
"created_at": "2027-01-20T10:00:00.000Z",
"updated_at": "2027-01-20T10:00:00.000Z"
}
Update a task template
PATCH /task-templates/{id} Scope templates:write
Send only the fields to change. tasks replaces the whole list, so read the template first and send back every task you want to keep. Giveaways already created keep the tasks they have.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | No | A new name, 25 characters at most. |
| description | string | No | A new description, 60 characters at most. |
| tasks | object[] | No | The new task list, at least one task. It replaces every task of the template. |
Request
curl -X PATCH "https://t.scoplidrop.com/v1/task-templates/00000000-0000-4000-8000-000000000020" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Launch week tasks"
}'
Response
{
"id": "00000000-0000-4000-8000-000000000020",
"name": "Launch week tasks",
"description": "Follow us and visit the site",
"tasks": [
{
"type": "youtube-subscribe",
"name": "Follow on YouTube",
"required": true,
"points": 1,
"config": {
"url": "https://youtube.com/@scoplidrop",
"proofType": "text",
"screenshotCount": "1",
"verificationMethod": "timer-based"
}
},
{
"type": "website-visit",
"name": "Visit website",
"required": false,
"points": 1,
"config": {
"url": "https://www.scoplidrop.com",
"customNote": "",
"verificationMethod": "timer-based"
}
}
],
"created_at": "2027-01-20T10:00:00.000Z",
"updated_at": "2027-01-22T09:30:00.000Z"
}
Delete a task template
DELETE /task-templates/{id} Scope templates:write
Deletes the template for good. Giveaways already created from it keep their tasks.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The id of the deleted template. |
| deleted | boolean | Always true. |
Request
curl -X DELETE "https://t.scoplidrop.com/v1/task-templates/00000000-0000-4000-8000-000000000020" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "00000000-0000-4000-8000-000000000020",
"deleted": true
}
Use a template in a giveaway
Pass template ids in task_template_ids when you create a giveaway. The tasks of the templates are merged in order, and a template whose tasks are not fully set up is refused.
Request
curl -X POST "https://t.scoplidrop.com/v1/giveaways" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"prize": "Discord Nitro (1 month)",
"channel_id": "100000000000000001",
"end": {
"type": "time",
"at": "2027-01-31T18:00:00Z"
},
"task_template_ids": [
"00000000-0000-4000-8000-000000000020"
]
}'
Economy
Read and adjust coin balances
The server's coin economy. In every economy endpoint, user_id is a Discord id.
Get a member's balance
GET /economy/balances/{user_id} Scope economy:read
A member who never earned coins reads as zero.
Response fields
| Field | Type | Description |
|---|---|---|
| user_id | string | The member's Discord id. |
| username | string | null | The member's Discord username, when ScopliDrop knows it. |
| balance | integer | The coins the member holds now. |
| total_earned | integer | The coins the member has earned on this server in total. |
| total_spent | integer | The coins the member has spent on this server in total. |
Request
curl "https://t.scoplidrop.com/v1/economy/balances/200000000000000001" \
-H "Authorization: Bearer sdrop_..."
Response
{
"user_id": "200000000000000001",
"username": "example_member",
"balance": 1250,
"total_earned": 4300,
"total_spent": 3050
}
Adjust a member's balance
POST /economy/balances/{user_id}/adjust Scope economy:write
The member who created the key needs the permission to manage the server's economy.
This endpoint accepts an Idempotency-Key header, so sending the same request again does not repeat the write. Read how idempotency keys work.
Body fields
| Field | Type | Required | Description |
|---|---|---|---|
| amount | integer | Yes | A whole number that is not zero. A positive amount adds coins, a negative amount takes them away. |
| reason | string | No | Up to 500 characters. Shown in the transaction log. |
Response fields
| Field | Type | Description |
|---|---|---|
| user_id | string | The member's Discord id. |
| balance | integer | The balance after the change. |
| amount_applied | integer | The signed amount that was applied. |
Request
curl -X POST "https://t.scoplidrop.com/v1/economy/balances/200000000000000001/adjust" \
-H "Authorization: Bearer sdrop_..." \
-H "Content-Type: application/json" \
-d '{
"amount": 500,
"reason": "Community event prize"
}'
Response
{
"user_id": "200000000000000001",
"balance": 1750,
"amount_applied": 500
}
Get the leaderboard
GET /economy/leaderboard Scope economy:read
Members with a balance above zero, richest first. Each item is a balance object with one more field.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| rank | integer | The position by balance, starting at 1. |
Request
curl "https://t.scoplidrop.com/v1/economy/leaderboard?limit=2" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"rank": 1,
"user_id": "200000000000000002",
"username": "another_member",
"balance": 9800,
"total_earned": 15200,
"total_spent": 5400
},
{
"rank": 2,
"user_id": "200000000000000001",
"username": "example_member",
"balance": 1750,
"total_earned": 4800,
"total_spent": 3050
}
],
"next_cursor": "eyJ2IjoxLCJvIjoyfQ"
}
List transactions
GET /economy/transactions Scope economy:read
The transaction log, newest first.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| user_id | string | Only the transactions of this member. |
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The transaction id. |
| user_id | string | The member's Discord id. |
| type | string | What moved the coins, for example admin_grant or admin_deduct. |
| amount | integer | The signed change. Positive adds coins, negative removes them. |
| balance_after | integer | The member's balance once the change was applied. |
| reason | string | null | The reason given with an adjustment. |
| created_at | string | null | When the coins moved. |
Request
curl "https://t.scoplidrop.com/v1/economy/transactions?user_id=200000000000000001" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "00000000-0000-4000-8000-000000000020",
"user_id": "200000000000000001",
"type": "admin_grant",
"amount": 500,
"balance_after": 1750,
"reason": "Community event prize",
"created_at": "2027-01-25T10:15:00.000Z"
}
],
"next_cursor": null
}
Get the economy summary
GET /economy/summary Scope economy:read
What moved the coins over a rolling period or a custom range of dates, in total and for each type of movement. The totals cover every transaction of the period, so there is nothing to page through or add up. A period that holds too many transactions to add up in one call is refused with invalid_request. Ask for a shorter one.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| period | string | A rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Defaults to 30d. |
| from | string | The first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period. |
| to | string | The last day of a custom range, written YYYY-MM-DD, in UTC. The whole day is included. A range covers 366 days at most. |
Response fields
| Field | Type | Description |
|---|---|---|
| period | string | The rolling period that was asked for, or custom for a range of dates. |
| from | string | The start of the period. |
| to | string | The end of the period. For a rolling period, the moment of the call. |
| transactions | integer | Transactions in the period. |
| members | integer | Distinct members with at least one transaction in the period. |
| coins_added | integer | The sum of every positive amount. |
| coins_removed | integer | The sum of every negative amount, as a positive number. |
| net | integer | coins_added minus coins_removed. |
| by_type | object[] | The same totals for each type of movement, largest volume first. Each item has type, transactions, members, coins_added and coins_removed. |
Request
curl "https://t.scoplidrop.com/v1/economy/summary?period=30d" \
-H "Authorization: Bearer sdrop_..."
Response
{
"period": "30d",
"from": "2027-01-01T12:00:00.000Z",
"to": "2027-01-31T12:00:00.000Z",
"transactions": 5210,
"members": 640,
"coins_added": 48200,
"coins_removed": 12900,
"net": 35300,
"by_type": [
{
"type": "activity_earn",
"transactions": 5100,
"members": 640,
"coins_added": 41200,
"coins_removed": 0
},
{
"type": "auction_bid",
"transactions": 48,
"members": 21,
"coins_added": 0,
"coins_removed": 12400
},
{
"type": "admin_grant",
"transactions": 60,
"members": 60,
"coins_added": 7000,
"coins_removed": 0
},
{
"type": "admin_deduct",
"transactions": 2,
"members": 2,
"coins_added": 0,
"coins_removed": 500
}
]
}
Analytics
Read the analytics overview
Headline numbers for a rolling period that ends now, or for a custom range of dates. They come from the same data as the dashboard's analytics overview.
Get the overview
GET /analytics/overview Scope analytics:read
Query parameters
| Parameter | Type | Description |
|---|---|---|
| period | string | A rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Defaults to 30d. |
| from | string | The first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period. |
| to | string | The last day of a custom range, written YYYY-MM-DD, in UTC. The whole day is included. A range covers 366 days at most. |
Response fields
| Field | Type | Description |
|---|---|---|
| period | string | The rolling period that was asked for, or custom for a range of dates. |
| from | string | The start of the period. |
| to | string | The end of the period. For a rolling period, the moment of the call. |
| giveaways | integer | Giveaways in the period. |
| entries | integer | Entries in the period. |
| unique_participants | integer | Distinct members who entered in the period. |
| returning_participants | integer | Participants of this period who had already entered a giveaway before. |
| entry_sources | object[] | Entries by where members entered from. Each item has source and count. |
| top_giveaways | object[] | The top giveaways of the period. Each item has id, prize, status and unique_participants. |
| server_members | integer | The member count of the server. |
| active_members | integer | null | Members active in the period. Null when activity tracking is off on the server. |
Request
curl "https://t.scoplidrop.com/v1/analytics/overview?period=30d" \
-H "Authorization: Bearer sdrop_..."
Response
{
"period": "30d",
"from": "2027-01-01T12:00:00.000Z",
"to": "2027-01-31T12:00:00.000Z",
"giveaways": 6,
"entries": 1840,
"unique_participants": 950,
"returning_participants": 410,
"entry_sources": [
{
"source": "discord-embed",
"count": 1310
},
{
"source": "share-link",
"count": 530
}
],
"top_giveaways": [
{
"id": "00000000-0000-4000-8000-000000000001",
"prize": "Discord Nitro (1 month)",
"status": "ended",
"unique_participants": 305
}
],
"server_members": 12400,
"active_members": null
}
Features
List everything ScopliDrop can do
The catalog of ScopliDrop features, with the plan each one starts on and the page that explains it. Most features are set in the ScopliDrop dashboard and have no endpoint, so an integration or an AI assistant reads the catalog to say what exists and where to find it.
List features
GET /features No scope needed
Returns every feature in one answer, in the list shape. The catalog is never paged, so next_cursor is always null. It is the same for every server.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| category | string | Only the features of one category. One of tasks, running-giveaways, anti-cheat, growth, automation, engagement, analytics, integrations, teams. |
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The feature id, for example winner-cooldowns. |
| name | string | The name of the feature. |
| category | string | The category id. |
| plan | string | The lowest plan the feature starts on. One of free, premium, business and enterprise. Parts of a feature can need a higher plan, which its page says. |
| summary | string | What the feature does, in one sentence. |
| url | string | null | The page of the feature on scoplidrop.com. Null for a feature that has no page yet. |
Request
curl "https://t.scoplidrop.com/v1/features?category=analytics" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "participant-crm",
"name": "Participant CRM",
"category": "analytics",
"plan": "business",
"summary": "Unified contact profiles built from every identity field participants submit.",
"url": "https://www.scoplidrop.com/features/participant-crm"
},
{
"id": "giveaway-analytics",
"name": "Giveaway Analytics",
"category": "analytics",
"plan": "premium",
"summary": "Entries, task completion, referrals, and fraud metrics for every giveaway and your whole server.",
"url": "https://www.scoplidrop.com/features/giveaway-analytics"
},
{
"id": "email-collection",
"name": "Email Collection",
"category": "analytics",
"plan": "premium",
"summary": "Collect entrant emails as a task and own your audience data.",
"url": null
}
],
"next_cursor": null
}
Get a feature
GET /features/{id} No scope needed
Returns one feature in full. An id outside the catalog answers not_found.
Response fields
The fields of the list, and two more.
| Field | Type | Description |
|---|---|---|
| details | string[] | What the feature does, as paragraphs. Empty for a feature that has no page yet. |
| how_it_works | object[] | How it works, step by step. Each item has title and description. Can be empty. |
Request
curl "https://t.scoplidrop.com/v1/features/winner-cooldowns" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "winner-cooldowns",
"name": "Winner Cooldowns",
"category": "anti-cheat",
"plan": "premium",
"summary": "Lock recent winners out of the draw for the days or the number of giveaways you choose, so the same members stop winning every giveaway.",
"url": "https://www.scoplidrop.com/features/winner-cooldowns",
"details": [
"A winner cooldown is a rule you set when you build a ScopliDrop giveaway. Anyone who won a giveaway in your Discord server within the window you choose is passed over when winners are drawn. Measure the window in days, from 1 to 365, or in giveaways, so a member who won sits out the next 3 draws however far apart they run. Our giveaway bot for Discord tracks who won and when on its own."
],
"how_it_works": [
{
"title": "Switch it on and pick the window",
"description": "One toggle in the builder's winners section, set to the number of days or the number of giveaways a win should sit someone out. Giveaway templates and quickstart defaults carry it into future giveaways."
},
{
"title": "Members enter as usual, with the rule in the entry terms",
"description": "Entry stays open to everyone, on every entry mode. On the web entry page, the cooldown is listed among the giveaway's key terms with the exact number of days."
}
]
}
Updates
Read what changed in ScopliDrop
The update notes of the public ScopliDrop changelog, newest first. Each note is one update with the changes it covers, so an integration or an AI assistant can say what is new, or what changed since a given day.
List updates
GET /updates No scope needed
Newest first. With a period or a range, only the notes that went out in it. Without one, the newest notes, however old. The list leaves out the text of each note. It is the same for every server.
Query parameters
| Parameter | Type | Description |
|---|---|---|
| period | string | A rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Leave out period, from and to for the newest notes. |
| from | string | The first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period. |
| to | string | The last day of a custom range, written YYYY-MM-DD, in UTC. The whole day is included. A range covers 366 days at most. |
| limit | integer | Page size, 1 to 100. Defaults to 25. |
| cursor | string | The next_cursor of the previous page. Leave it out for the first page. |
Response fields
| Field | Type | Description |
|---|---|---|
| id | string | The update id, the day it went out, for example 2026-11-04. A second note on the same day ends in -2. |
| date | string | The day it went out, written YYYY-MM-DD. |
| title | string | The title of the note. |
| new_features | integer | How many new features it brought, not counting improvements and fixes. |
| summary | string | null | Its opening paragraph. Null when the note starts on a heading. |
| highlights | string[] | The section headings of the note, in order. The smaller changes sit under the last one, often Also in this update. |
| url | string | The note on the ScopliDrop changelog page. |
Request
curl "https://t.scoplidrop.com/v1/updates?period=30d" \
-H "Authorization: Bearer sdrop_..."
Response
{
"data": [
{
"id": "2026-11-04",
"date": "2026-11-04",
"title": "Giveaway republishing is here",
"new_features": 4,
"summary": "Your giveaways can now run in other servers too, with one shared draw.",
"highlights": [
"Republish your giveaways in other servers",
"Draw when your server hits a member goal",
"Time in Server task",
"Also in this update"
],
"url": "https://www.scoplidrop.com/changelog#2026-11-04"
}
],
"next_cursor": null
}
Get an update
GET /updates/{id} No scope needed
Returns one note in full. An id that is not a note answers not_found.
Response fields
The fields of the list, and one more.
| Field | Type | Description |
|---|---|---|
| body | string | The whole note as markdown. Images are left out and links to ScopliDrop pages are absolute. |
Request
curl "https://t.scoplidrop.com/v1/updates/2026-11-04" \
-H "Authorization: Bearer sdrop_..."
Response
{
"id": "2026-11-04",
"date": "2026-11-04",
"title": "Giveaway republishing is here",
"new_features": 4,
"summary": "Your giveaways can now run in other servers too, with one shared draw.",
"highlights": [
"Republish your giveaways in other servers",
"Draw when your server hits a member goal",
"Time in Server task",
"Also in this update"
],
"url": "https://www.scoplidrop.com/changelog#2026-11-04",
"body": "Your giveaways can now run in other servers too, with one shared draw.\n\n## Republish your giveaways in other servers\n\nPartner up with other communities and reach way more people than your own server."
}
AI assistants
Use the API from an AI assistant
ScopliDrop runs an MCP server next to the REST API. It accepts the same API keys and offers the same operations as tools, so an assistant can do what the key's scopes allow.
MCP server URL
https://t.scoplidrop.com/mcp
Add it to Claude Code
claude mcp add --transport http scoplidrop https://t.scoplidrop.com/mcp --header "Authorization: Bearer sdrop_..."
MCP tools and the endpoints they run
Each tool runs the endpoint next to it, with the same scope, rules and errors. A tool the key has no scope for is not listed.
| Tool | Endpoint | What it does |
|---|---|---|
| list_servers | GET /server | Get the server |
| list_channels | GET /server/channels | List channels |
| list_roles | GET /server/roles | List roles |
| list_giveaways | GET /giveaways | List giveaways |
| get_giveaway | GET /giveaways/{id} | Get a giveaway |
| create_giveaway | POST /giveaways | Create a giveaway |
| update_giveaway | PATCH /giveaways/{id} | Update a giveaway |
| end_giveaway | POST /giveaways/{id}/end | End a giveaway now |
| reroll_giveaway | POST /giveaways/{id}/reroll | Reroll winners |
| list_giveaway_entries | GET /giveaways/{id}/entries | List entries |
| list_giveaway_winners | GET /giveaways/{id}/winners | List winners |
| list_scheduled_giveaways | GET /scheduled-giveaways | List scheduled giveaways |
| get_scheduled_giveaway | GET /scheduled-giveaways/{id} | Get a scheduled giveaway |
| schedule_giveaway | POST /scheduled-giveaways | Schedule a giveaway |
| update_scheduled_giveaway | PATCH /scheduled-giveaways/{id} | Update a scheduled giveaway |
| cancel_scheduled_giveaway | DELETE /scheduled-giveaways/{id} | Cancel a scheduled giveaway |
| list_task_types | GET /task-types | List task types |
| get_task_type | GET /task-types/{type} | Get a task type |
| list_task_templates | GET /task-templates | List task templates |
| get_task_template | GET /task-templates/{id} | Get a task template |
| create_task_template | POST /task-templates | Create a task template |
| update_task_template | PATCH /task-templates/{id} | Update a task template |
| delete_task_template | DELETE /task-templates/{id} | Delete a task template |
| get_member_balance | GET /economy/balances/{user_id} | Get a member's balance |
| adjust_member_balance | POST /economy/balances/{user_id}/adjust | Adjust a member's balance |
| list_coin_leaderboard | GET /economy/leaderboard | Get the leaderboard |
| list_coin_transactions | GET /economy/transactions | List transactions |
| get_economy_summary | GET /economy/summary | Get the economy summary |
| get_analytics_overview | GET /analytics/overview | Get the overview |
| list_features | GET /features | List features |
| get_feature | GET /features/{id} | Get a feature |
| list_updates | GET /updates | List updates |
| get_update | GET /updates/{id} | Get an update |
- Call list_servers first. It shows the server the key acts on, its plan and what the key may do.
- schedule_giveaway posts nothing at once. The giveaway is announced at its start time, and each run of a series at its own time. create_giveaway is the tool that announces a giveaway now.
To be told when something happens instead of polling, read the ScopliDrop webhooks documentation. Events carry the giveaway and entry objects described on this page.
To let your own app confirm that a member completed a task, read the Verified Actions developer documentation.
API keys and the MCP server are part of the Business and Enterprise plans. Plans are compared on the ScopliDrop pricing page.