ScopliDrop Developer Docs

ScopliDrop REST API

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
view raw
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. 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. 2

    Pick the scopes the key needs and when it expires: in 30 days, in 90 days, in 1 year or never.

  3. 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. 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.

ScopeAllows
giveaways:readList giveaways and scheduled giveaways, and read one giveaway, its entries and its winners.
giveaways:writeCreate, schedule and edit giveaways, cancel a schedule, end giveaways and reroll winners.
templates:readList task templates and read one, with the settings of its tasks.
templates:writeCreate, edit and delete task templates.
economy:readRead coin balances, the leaderboard and the transaction log.
economy:writeAdd coins to a member's balance or take coins away.
analytics:readRead 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.

Errors

Errors share one JSON shape

Every failure, an unknown path included, answers with an error object and the matching HTTP status.

{
  "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.
CodeStatusWhen it happens
invalid_request400The 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.
unauthorized401The API key is missing, not valid, revoked or expired.
forbidden403The key lacks the scope the endpoint needs, or the member who created the key is not allowed to do this on the server.
plan_required403The 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_found404The resource does not exist on this server, or the path is not a v1 endpoint.
conflict409The 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_limited429Too many requests. Wait for the number of seconds in the Retry-After header.
server_error500Something went wrong on our side. After a failed write, read the resource before you retry.
upstream_unavailable503ScopliDrop or Discord could not be reached, and nothing was changed. Send the request again in a moment.
outcome_unknown502, 504A 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.

ParameterTypeDescription
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe 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.

LimitCounted for
120 requests per minuteEach API key, every request.
20 writes per minuteEach API key, every POST, PATCH and DELETE. A write also counts toward the 120.
300 requests per minuteEach 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.

EndpointWhat it does
POST /giveawaysCreate a giveaway
PATCH /giveaways/{id}Update a giveaway
POST /giveaways/{id}/endEnd a giveaway now
POST /giveaways/{id}/rerollReroll winners
POST /scheduled-giveawaysSchedule a giveaway
PATCH /scheduled-giveaways/{id}Update a scheduled giveaway
DELETE /scheduled-giveaways/{id}Cancel a scheduled giveaway
POST /task-templatesCreate a task template
PATCH /task-templates/{id}Update a task template
DELETE /task-templates/{id}Delete a task template
POST /economy/balances/{user_id}/adjustAdjust 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/serverNo scope needed
FieldTypeDescription
idstringThe Discord server id.
namestring | nullThe server name as the bot last saw it.
planstringThe server's plan.
key.idstringThe id of the API key behind the call.
key.namestringThe name given to the key in the dashboard.
key.scopesstring[]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/channelsNo 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

ParameterTypeDescription
searchstringOnly 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.
typestringOnly the channels of one type: text, announcement, voice, stage or forum.
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
idstringThe Discord channel id.
namestringThe channel name.
typestringOne of text, announcement, voice, stage and forum. A giveaway is announced in a text or announcement channel.
categorystring | nullThe name of the category the channel sits under. Null for a channel outside any category.
bot_can_postboolean | nullWhether the ScopliDrop bot can post a giveaway in the channel. Null when the bot could not be asked just now.
missing_permissionsstring[]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/rolesNo 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

ParameterTypeDescription
searchstringOnly 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.
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
idstringThe Discord role id.
namestringThe role name.
mentionablebooleanWhether members can mention the role.
managedbooleanTrue 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.

FieldTypeDescription
idstringThe giveaway id.
statusstringOne of active or ended. A giveaway waiting for its start is a scheduled giveaway, read with GET /scheduled-giveaways.
prizestringWhat the winners get.
descriptionstring | nullThe description shown under the prize.
image_urlstring | nullThe image of the giveaway.
winner_countintegerHow many winners are drawn.
starts_atstringWhen the giveaway starts.
ends_atstring | nullWhen the giveaway ends, or the moment it ended. Null while it runs with no end date.
end_conditionobjectHow the giveaway ends. See the table below.
channel_idstringThe Discord channel the giveaway is announced in.
message_idstring | nullThe Discord announcement message. Null until the bot has posted it.
urlstring | nullThe public giveaway page.
entries_countintegerTotal entries in the draw. One member can hold several.
participants_countintegerHow many members have entered.
requirements.minimum_account_age_daysintegerMinimum age of the Discord account in days. 0 means no minimum.
requirements.require_2fabooleanWhether members who enter through the giveaway page need two-factor authentication on their Discord account.
announcements.winner_channel_idstring | nullThe channel for the winner announcement. Null means the giveaway's own channel.
announcements.ping_role_idsstring[]The roles pinged in the giveaway's Discord posts.
tasksobject[]The entry tasks. Each has type, name, required and points. The settings of a task are never returned here. A task template returns them.
winnersobject[] | nullNull until the giveaway has ended. Then one object per winner in draw order, with position (starting at 1), user_id and prize.
created_atstringWhen the giveaway was created.

End conditions

end_conditionMeaning
{ "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/giveawaysScope giveaways:read

Giveaways come newest first.

Query parameters

ParameterTypeDescription
statusstringOnly giveaways with this status: active or ended. Giveaways waiting for their start are listed by GET /scheduled-giveaways.
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe 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/giveawaysScope 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

FieldTypeRequiredDescription
prizestringYesWhat the winners get. 1 to 150 characters.
channel_idstringYesThe Discord channel the giveaway is announced in.
endobjectYesHow the giveaway ends. See the table below.
descriptionstringNoUp to 500 characters.
imageobjectNoAn object with url and an optional placement. The placement is embed (inside the announcement, the default) or separate_message (posted above it).
winner_countintegerNo1 to 10,000. Defaults to 1.
announcements.winner_channel_idstringNoThe channel for the winner announcement. Defaults to the giveaway's channel.
announcements.ping_role_idsstring[]NoThe roles to ping in the giveaway's Discord posts.
requirements.minimum_account_age_daysintegerNoMinimum age of the Discord account in days, 0 to 365. Defaults to 0.
requirements.require_2fabooleanNoWhether members who enter through the giveaway page need two-factor authentication on their Discord account. Defaults to false.
tasksobject[]NoEntry 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_idsstring[]No1 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

endMeaning
{ "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

FieldTypeRequiredDescription
descriptionstringNoUp to 500 characters.
imageobject | nullNoSame object as on create. null removes the image.
winner_countintegerNo1 to 10,000.
endobjectNoReplaces the end condition as a whole. Same shapes as on create, except that member_goal must name its date in at.
announcements.winner_channel_idstring | nullNoThe channel for the winner announcement. null goes back to the giveaway's own channel.
announcements.ping_role_idsstring[]NoThe roles to ping in the giveaway's Discord posts.
add_tasksobject[]NoTasks 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_participantsbooleanNoWhether 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}/endScope 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}/rerollScope 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

FieldTypeRequiredDescription
user_idsstring[]NoThe Discord ids of the winners to replace. Leave it out to draw every winner again.

Response fields

FieldTypeDescription
giveawayobjectThe giveaway with its new winners.
previous_winnersstring[]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}/entriesScope giveaways:read

Entries come in the order members entered, oldest first, so pages stay put while new entries arrive.

Query parameters

ParameterTypeDescription
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
idstringThe entry id.
user_idstringThe member's Discord id.
usernamestring | nullThe Discord username the member entered under.
entriesintegerHow many entries this member holds in the draw.
sourcestring | nullWhere the member entered from, for example discord-embed or share-link.
created_atstringWhen 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}/winnersScope giveaways:read

Winners come in draw order. The list is empty until the giveaway has ended.

Query parameters

ParameterTypeDescription
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
positionintegerThe draw position, starting at 1.
user_idstringThe winner's Discord id.
prizestringWhat this position wins.
usernamestring | nullThe 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.

FieldTypeDescription
idstringThe id of the schedule.
namestringThe name shown in the dashboard. Defaults to the prize.
statusstringWhere the schedule stands. See the table below.
starts_atstringWhen the giveaway is posted. For a series, when its first run is posted.
next_run_atstring | nullWhen the next giveaway is posted. Null when nothing is left to post.
endobjectHow each giveaway it posts ends, in the shape it was sent.
recurrenceobject | nullThe 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.
giveawayobjectWhat it posts, in short. An object with prize, channel_id and winner_count.
launched_giveaway_idstring | nullThe id of the giveaway it posted, to read with the giveaway endpoints. Null until a giveaway has been posted.
errorstring | nullWhy the giveaway could not be posted, when the status is failed. Null otherwise.
created_atstringWhen the schedule was created.

Statuses

statusMeaning
pendingA one-time schedule waiting for its start.
launchedA one-time schedule whose giveaway has been posted.
failedA one-time schedule whose giveaway could not be posted. The error field says why.
recurringA running series. It posts a giveaway on each run of its rule.
pausedA series on pause. It posts nothing until it is resumed.
endedA 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-giveawaysScope giveaways:read

The schedules of the server, the next one to be posted first.

Query parameters

ParameterTypeDescription
statusstringOnly schedules with this status: pending, launched, failed, recurring, paused or ended.
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe 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-giveawaysScope 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.

FieldTypeRequiredDescription
starts_atstringNoWhen 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.
endobjectYesHow each giveaway ends. See the table below. A series takes duration only.
recurrenceobjectNoThe rule of a series. See the table below. Leave it out for a one-time giveaway.
namestringNoThe name shown in the dashboard, 50 characters at most. Defaults to the prize.

The end object of a schedule

endMeaning
{ "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

FieldTypeRequiredDescription
frequencystringYesOne of daily, weekly and monthly.
timestringYesThe time of each run, written HH:MM on a 24 hour clock, in timezone.
timezonestringYesAn IANA time zone, for example Europe/Paris. Runs keep their local time when the clocks change.
intervalintegerNoRun every how many days, weeks or months, 1 to 52. Defaults to 1.
days_of_weekstring[]NoThe days a weekly series runs on, at least one, among mon, tue, wed, thu, fri, sat and sun. Weekly only.
day_of_monthintegerNoThe 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_atstringNoNo run starts after this date, an ISO 8601 date with a time zone. Leave it out for a series with no end date.
max_runsintegerNoThe 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

FieldTypeRequiredDescription
namestringNoA new name, 50 characters at most.
starts_atstringNoA new start in the future. For a series, when its next run is posted.
endobjectNoReplaces the end as a whole. Same shapes as on create, and a series keeps a duration.
recurrenceobjectNoReplaces the rule of a series as a whole. Same object as on create.
pausedbooleanNotrue 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.

FieldTypeRequiredDescription
typestringYesThe task type, a type from the task type list, for example youtube-subscribe.
configobjectNoThe settings of that task type. Send only the settings you want to set. They are laid over the defaults of the type.
namestringNoThe name members see. Defaults to the name of the task type.
requiredbooleanNoWhether a member must complete the task to enter. Defaults to false. Not accepted in add_tasks.
pointsintegerNoThe 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-typesNo 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

ParameterTypeDescription
categorystringOnly the task types of one category. One of social, discord, community, web, music, games, roblox, custom.

The task type object

FieldTypeDescription
typestringWhat goes in the type of a task.
namestringThe name of the task type. It is the default name of a task.
categorystringThe category id, for example social or discord.
category_namestringThe category as the dashboard names it.
descriptionstringWhat the task asks of a member.
planstringThe lowest plan of the server that can use this task type. One of free, premium, business and enterprise.
notesstring[]Things to know that are not a setting, for example that the server needs Leveling turned on.
config_fieldsobject[]The settings a task of this type takes, in the order of the dashboard.
default_configobjectWhat 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.

FieldTypeDescription
keystringThe key inside config.
typestringHow the value is written. One of string, url, number, boolean, enum, string[], object and object[].
labelstringThe name of the setting in the dashboard.
descriptionstringWhat the setting does.
requiredbooleanTrue when the task type has no default for it, so a task must send it.
defaultanyWhat the setting holds when it is left out.
optionsobject[]The allowed values of an enum. Each has value and label, and plan when that value needs a higher plan than the task type.
examplestringAn example value.
patternstringA regular expression the value must match.
min, maxnumberThe bounds of a number.
max_lengthintegerThe longest text allowed, in characters.
max_itemsintegerThe most items a list may hold.
premiumbooleanTrue when values other than the default need the Premium plan.
shown_whenobject[]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.

TypeNamePlanConfig keys
youtube-subscribeFollow on YouTubefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
youtube-likeLike YouTube videofreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
youtube-commentComment YouTube videofreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
discord-joinJoin Discord ServerfreeserverId, inviteUrl, verificationMethod
x-followFollow on Xfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
x-likeLike X postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
x-repostRepost on Xfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
x-commentComment X postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
x-postPost on XpremiumpostText, verificationMethod, proofType, screenshotCount, screenshotInstructions
instagram-followFollow on Instagramfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
instagram-likeLike Instagram postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
instagram-commentComment Instagram postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
instagram-repostRepost in Instagram storyfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
instagram-tag-friendsTag friends in IG commentfreeurl, friendCount, verificationMethod, proofType, screenshotCount, screenshotInstructions
facebook-followFollow on Facebookfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
facebook-join-groupJoin Facebook groupfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
facebook-like-postLike Facebook postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
facebook-commentComment Facebook postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
facebook-watchWatch Facebook videofreeurl, minTime, verificationMethod, videoCodes
twitch-followFollow on Twitchfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
twitch-subscribeSubscribe on Twitchfreeurl, minTier, verificationMethod, proofType, screenshotCount, screenshotInstructions
discord-role-checkHave Discord RolefreeroleIds, customNote
discord-role-assignClaim Discord RolefreeroleId, customNote
discord-voice-timeVoice Channel ActivityfreeminValue, aggregationMode, timeWindowDays
discord-message-countMessage ActivityfreeminValue, aggregationMode, timeWindowDays
discord-xp-levelReach XP/LevelfreerequirementType, minValue
discord-member-sinceTime in ServerpremiummemberSinceMode, minMemberDays
scoplidrop-giveaway-regularGiveaway RegularfreeminGiveaways, timeWindowDays
scoplidrop-play-minigamesPlay MinigamesfreeminGames, gameType, timeWindow, minOpponents
website-visitVisit websitefreeurl, customNote
collect-emailProvide EmailpremiumcustomNote
tiktok-followFollow on TikTokfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
tiktok-likeLike TikTok videofreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
tiktok-commentComment TikTok videofreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
tiktok-repostRepost TikTok videofreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
telegram-join-groupJoin Telegram groupfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
telegram-view-postView Telegram postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
kick-followFollow on Kickfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
kick-subscribeSubscribe on Kickfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
kick-watchWatch Kick streamfreeurl, minTime, verificationMethod, videoCodes
pinterest-followFollow on Pinterestfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
pinterest-visitVisit Pinterest pagefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
reddit-visit-subredditVisit subredditfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
reddit-follow-subredditFollow subredditfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
reddit-follow-userFollow Reddit userfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
spotify-follow-artistFollow Spotify artistfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
spotify-follow-playlistFollow Spotify playlistfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
spotify-listen-songListen to Spotify songfreeurl, minTime, verificationMethod
spotify-save-songSave Spotify songfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
spotify-pre-savePre-save on Spotifyfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
bluesky-followFollow on Blueskyfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
bluesky-likeLike Bluesky postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
bluesky-repostRepost on Blueskyfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
snapchat-followFollow on Snapchatfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
linkedin-follow-companyFollow LinkedIn companyfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
linkedin-follow-userFollow LinkedIn userfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
linkedin-connect-userConnect to LinkedIn userfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
youtube-watchWatch YouTube videofreeurl, minTime, verificationMethod, videoCodes
tiktok-watchWatch TikTok videofreeurl, minTime, verificationMethod, videoCodes
twitch-watchWatch Twitch streamfreeurl, minTime, verificationMethod, videoCodes
instagram-watchWatch Instagram Reelfreeurl, minTime, verificationMethod, videoCodes
scoplidrop-topgg-upvoteUpvote ScopliDrop on Top.ggfreeNone
scoplidrop-lootbox-openOpen the lootboxfreeNone
scoplidrop-listing-upvoteUpvote this giveaway on ScopliDropfreeNone
soundcloud-listen-songListen to SoundCloud songfreeurl, minTime, verificationMethod
soundcloud-like-songLike SoundCloud songfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
soundcloud-repost-songRepost SoundCloud songfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
soundcloud-follow-artistFollow SoundCloud artistfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
patreon-visitVisit Patreon pagefreeurl
meta-quest-wishlistAdd to Meta Wishlistfreeurl, verificationMethod
steam-wishlistWishlist on Steampremiumurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
steam-follow-gameFollow a game on Steamfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
steam-join-groupJoin a Steam groupfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
roblox-join-communityJoin a Roblox Communityfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions, minRank, minAccountAgeDays
roblox-feature-communityFeature a Roblox Community on Your Profilefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions, minAccountAgeDays
roblox-badgeEarn a Roblox Badgefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions, badgeWindow, minAccountAgeDays
roblox-own-itemOwn a Roblox Game Pass or Itemfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions, extraItems, minAccountAgeDays
roblox-profile-textAdd Text to Your Roblox ProfilefreeprofileText, profilePlace, verificationMethod, proofType, screenshotCount, screenshotInstructions, minAccountAgeDays
roblox-forum-commentComment on a Roblox Forum Postfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions, commentWindow, minAccountAgeDays
roblox-play-gamePlay a Roblox Gamefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
roblox-follow-gameFollow a Roblox Gamefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
roblox-favorite-gameFavorite a Roblox Gamefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
roblox-like-gameLike a Roblox Gamefreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
roblox-follow-userFollow on Robloxfreeurl, verificationMethod, proofType, screenshotCount, screenshotInstructions
discord-primary-guildSet Discord Server TagpremiumserverId, serverName, verificationMethod
combo-taskCombo Taskpremiumplatform, actions, url, minTime, verificationMethod, proofType, screenshotCount, screenshotInstructions
custom-taskCustom TaskbusinesscustomName, 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

FieldTypeDescription
idstringThe id of the template. It is what task_template_ids takes.
namestringThe name of the template.
descriptionstring | nullWhat the template is for.
tasksobject[]The tasks in order. Each has type, name, required, points and config, the settings of the task.
created_atstring | nullWhen the template was created.
updated_atstring | nullWhen 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-templatesScope templates:read

Returns the task templates of the server, newest first.

Query parameters

ParameterTypeDescription
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe 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-templatesScope 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

FieldTypeRequiredDescription
namestringYesThe name of the template, 25 characters at most.
tasksobject[]YesThe tasks, at least one, in the order members see them. Each is written as described under how a task is written.
descriptionstringNoWhat 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

FieldTypeRequiredDescription
namestringNoA new name, 25 characters at most.
descriptionstringNoA new description, 60 characters at most.
tasksobject[]NoThe 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

FieldTypeDescription
idstringThe id of the deleted template.
deletedbooleanAlways 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

FieldTypeDescription
user_idstringThe member's Discord id.
usernamestring | nullThe member's Discord username, when ScopliDrop knows it.
balanceintegerThe coins the member holds now.
total_earnedintegerThe coins the member has earned on this server in total.
total_spentintegerThe 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}/adjustScope 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

FieldTypeRequiredDescription
amountintegerYesA whole number that is not zero. A positive amount adds coins, a negative amount takes them away.
reasonstringNoUp to 500 characters. Shown in the transaction log.

Response fields

FieldTypeDescription
user_idstringThe member's Discord id.
balanceintegerThe balance after the change.
amount_appliedintegerThe 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/leaderboardScope economy:read

Members with a balance above zero, richest first. Each item is a balance object with one more field.

Query parameters

ParameterTypeDescription
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
rankintegerThe 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/transactionsScope economy:read

The transaction log, newest first.

Query parameters

ParameterTypeDescription
user_idstringOnly the transactions of this member.
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
idstringThe transaction id.
user_idstringThe member's Discord id.
typestringWhat moved the coins, for example admin_grant or admin_deduct.
amountintegerThe signed change. Positive adds coins, negative removes them.
balance_afterintegerThe member's balance once the change was applied.
reasonstring | nullThe reason given with an adjustment.
created_atstring | nullWhen 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/summaryScope 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

ParameterTypeDescription
periodstringA rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Defaults to 30d.
fromstringThe first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period.
tostringThe 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

FieldTypeDescription
periodstringThe rolling period that was asked for, or custom for a range of dates.
fromstringThe start of the period.
tostringThe end of the period. For a rolling period, the moment of the call.
transactionsintegerTransactions in the period.
membersintegerDistinct members with at least one transaction in the period.
coins_addedintegerThe sum of every positive amount.
coins_removedintegerThe sum of every negative amount, as a positive number.
netintegercoins_added minus coins_removed.
by_typeobject[]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/overviewScope analytics:read

Query parameters

ParameterTypeDescription
periodstringA rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Defaults to 30d.
fromstringThe first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period.
tostringThe 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

FieldTypeDescription
periodstringThe rolling period that was asked for, or custom for a range of dates.
fromstringThe start of the period.
tostringThe end of the period. For a rolling period, the moment of the call.
giveawaysintegerGiveaways in the period.
entriesintegerEntries in the period.
unique_participantsintegerDistinct members who entered in the period.
returning_participantsintegerParticipants of this period who had already entered a giveaway before.
entry_sourcesobject[]Entries by where members entered from. Each item has source and count.
top_giveawaysobject[]The top giveaways of the period. Each item has id, prize, status and unique_participants.
server_membersintegerThe member count of the server.
active_membersinteger | nullMembers 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/featuresNo 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

ParameterTypeDescription
categorystringOnly the features of one category. One of tasks, running-giveaways, anti-cheat, growth, automation, engagement, analytics, integrations, teams.

Response fields

FieldTypeDescription
idstringThe feature id, for example winner-cooldowns.
namestringThe name of the feature.
categorystringThe category id.
planstringThe 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.
summarystringWhat the feature does, in one sentence.
urlstring | nullThe 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.

FieldTypeDescription
detailsstring[]What the feature does, as paragraphs. Empty for a feature that has no page yet.
how_it_worksobject[]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/updatesNo 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

ParameterTypeDescription
periodstringA rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Leave out period, from and to for the newest notes.
fromstringThe first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period.
tostringThe last day of a custom range, written YYYY-MM-DD, in UTC. The whole day is included. A range covers 366 days at most.
limitintegerPage size, 1 to 100. Defaults to 25.
cursorstringThe next_cursor of the previous page. Leave it out for the first page.

Response fields

FieldTypeDescription
idstringThe update id, the day it went out, for example 2026-11-04. A second note on the same day ends in -2.
datestringThe day it went out, written YYYY-MM-DD.
titlestringThe title of the note.
new_featuresintegerHow many new features it brought, not counting improvements and fixes.
summarystring | nullIts opening paragraph. Null when the note starts on a heading.
highlightsstring[]The section headings of the note, in order. The smaller changes sit under the last one, often Also in this update.
urlstringThe 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.

FieldTypeDescription
bodystringThe 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.

ToolEndpointWhat it does
list_serversGET /serverGet the server
list_channelsGET /server/channelsList channels
list_rolesGET /server/rolesList roles
list_giveawaysGET /giveawaysList giveaways
get_giveawayGET /giveaways/{id}Get a giveaway
create_giveawayPOST /giveawaysCreate a giveaway
update_giveawayPATCH /giveaways/{id}Update a giveaway
end_giveawayPOST /giveaways/{id}/endEnd a giveaway now
reroll_giveawayPOST /giveaways/{id}/rerollReroll winners
list_giveaway_entriesGET /giveaways/{id}/entriesList entries
list_giveaway_winnersGET /giveaways/{id}/winnersList winners
list_scheduled_giveawaysGET /scheduled-giveawaysList scheduled giveaways
get_scheduled_giveawayGET /scheduled-giveaways/{id}Get a scheduled giveaway
schedule_giveawayPOST /scheduled-giveawaysSchedule a giveaway
update_scheduled_giveawayPATCH /scheduled-giveaways/{id}Update a scheduled giveaway
cancel_scheduled_giveawayDELETE /scheduled-giveaways/{id}Cancel a scheduled giveaway
list_task_typesGET /task-typesList task types
get_task_typeGET /task-types/{type}Get a task type
list_task_templatesGET /task-templatesList task templates
get_task_templateGET /task-templates/{id}Get a task template
create_task_templatePOST /task-templatesCreate a task template
update_task_templatePATCH /task-templates/{id}Update a task template
delete_task_templateDELETE /task-templates/{id}Delete a task template
get_member_balanceGET /economy/balances/{user_id}Get a member's balance
adjust_member_balancePOST /economy/balances/{user_id}/adjustAdjust a member's balance
list_coin_leaderboardGET /economy/leaderboardGet the leaderboard
list_coin_transactionsGET /economy/transactionsList transactions
get_economy_summaryGET /economy/summaryGet the economy summary
get_analytics_overviewGET /analytics/overviewGet the overview
list_featuresGET /featuresList features
get_featureGET /features/{id}Get a feature
list_updatesGET /updatesList updates
get_updateGET /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.
Related docs

Events, verified tasks and plans

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.