---
name: scoplidrop-api
description: Use the ScopliDrop REST API to read and manage a Discord server's giveaways, scheduled and recurring giveaways, entry tasks, task templates, coin economy and analytics, and to look up what ScopliDrop can do. Use when writing code that calls the ScopliDrop API, or when running giveaways for someone through it.
---

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

- Base URL: `https://t.scoplidrop.com/v1`
- Authentication: `Authorization: Bearer <API key>`. A key starts with `sdrop_` and is created in the ScopliDrop dashboard under Developer, API keys and MCP.
- Reference for people: https://www.scoplidrop.com/developers/api
- MCP server, the same operations as tools with the same keys: `https://t.scoplidrop.com/mcp`

## Rules to follow

1. Creating a giveaway announces it in Discord at once and cannot be undone. Confirm the server, the channel, the prize and how it ends with the person before you call it.
2. Scheduling a giveaway (`POST /scheduled-giveaways`) announces nothing now. The giveaway is posted at `starts_at`, and each run of a series at its own time. Use it when the person names a later start or a repeating rule, and confirm the start, its time zone and the rule with them first.
3. Ending or rerolling a giveaway, cancelling a schedule, deleting or replacing the tasks of a task template, and adding or taking coins cannot be undone either. Ask first, unless the person asked for exactly that.
4. Never invent a Discord id or a link. Take channel and role ids from `GET /server/channels` and `GET /server/roles`. A task points at the channel, post or page the person named. Ask when you have neither.
5. Before writing a task of a type you have not used, read `GET /task-types/{type}` and send the settings it marks as required.
6. Send an `Idempotency-Key` header with every write (a new UUID for each write you intend to make), so a retry can never apply it twice.
7. After `outcome_unknown` the write may have been applied. Read the current state before you send it again.
8. Call `GET /server` first. It confirms the key works and shows its server, plan and scopes.
9. When the person asks whether ScopliDrop can do something, read `GET /features` before you answer. Most features are set in the dashboard and have no endpoint, so the API alone is not the whole product.
10. When the person asks what is new in ScopliDrop or what changed over a period, read `GET /updates` with that period, then `GET /updates/{id}` for a note in full.

## 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

- 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

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

## Errors

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

```json
{ "error": { "code": "invalid_request", "message": "The request is not valid.", "details": [{ "path": "end.at", "message": "..." }] } }
```

- `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 | Meaning |
| --- | --- | --- |
| `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

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.

- `limit`: Page size, 1 to 100. Defaults to 25.
- `cursor`: 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.

## Rate limits

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 keys

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.

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

## Every endpoint

| Method | Path | Scope | What it does |
| --- | --- | --- | --- |
| GET | `/server` | none | Get the server |
| GET | `/server/channels` | none | List channels |
| GET | `/server/roles` | none | List roles |
| GET | `/giveaways` | `giveaways:read` | List giveaways |
| GET | `/giveaways/{id}` | `giveaways:read` | Get a giveaway |
| POST | `/giveaways` | `giveaways:write` | Create a giveaway |
| PATCH | `/giveaways/{id}` | `giveaways:write` | Update a giveaway |
| POST | `/giveaways/{id}/end` | `giveaways:write` | End a giveaway now |
| POST | `/giveaways/{id}/reroll` | `giveaways:write` | Reroll winners |
| GET | `/giveaways/{id}/entries` | `giveaways:read` | List entries |
| GET | `/giveaways/{id}/winners` | `giveaways:read` | List winners |
| GET | `/scheduled-giveaways` | `giveaways:read` | List scheduled giveaways |
| GET | `/scheduled-giveaways/{id}` | `giveaways:read` | Get a scheduled giveaway |
| POST | `/scheduled-giveaways` | `giveaways:write` | Schedule a giveaway |
| PATCH | `/scheduled-giveaways/{id}` | `giveaways:write` | Update a scheduled giveaway |
| DELETE | `/scheduled-giveaways/{id}` | `giveaways:write` | Cancel a scheduled giveaway |
| GET | `/task-types` | none | List task types |
| GET | `/task-types/{type}` | none | Get a task type |
| GET | `/task-templates` | `templates:read` | List task templates |
| GET | `/task-templates/{id}` | `templates:read` | Get a task template |
| POST | `/task-templates` | `templates:write` | Create a task template |
| PATCH | `/task-templates/{id}` | `templates:write` | Update a task template |
| DELETE | `/task-templates/{id}` | `templates:write` | Delete a task template |
| GET | `/economy/balances/{user_id}` | `economy:read` | Get a member's balance |
| POST | `/economy/balances/{user_id}/adjust` | `economy:write` | Adjust a member's balance |
| GET | `/economy/leaderboard` | `economy:read` | Get the leaderboard |
| GET | `/economy/transactions` | `economy:read` | List transactions |
| GET | `/economy/summary` | `economy:read` | Get the economy summary |
| GET | `/analytics/overview` | `analytics:read` | Get the overview |
| GET | `/features` | none | List features |
| GET | `/features/{id}` | none | Get a feature |
| GET | `/updates` | none | List updates |
| GET | `/updates/{id}` | none | Get an update |

## Server

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` · scope none

Call it first to check a key. Returns the server object.

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

### List channels

`GET /server/channels` · scope none

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: `search` (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` (Only the channels of one type: text, announcement, voice, stage or forum.) Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

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

### List roles

`GET /server/roles` · scope none

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: `search` (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`.) Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

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

## 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_condition` is one of:

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

### List giveaways

`GET /giveaways` · scope `giveaways:read`

Giveaways come newest first.

Query: `status` (Only giveaways with this status: active or ended. Giveaways waiting for their start are listed by `GET /scheduled-giveaways`.). Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

Returns a page of giveaway objects.

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

Returns the giveaway object.

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

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

`end` is one of:

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

Returns the giveaway object.

### Update a giveaway

`PATCH /giveaways/{id}` · scope `giveaways:write`

Send only the fields to change, and at least one.

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

Returns the giveaway object.

### 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`.

No body. Returns the giveaway object, ended, with its winners.

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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `user_ids` | string[] | no | The Discord ids of the winners to replace. Leave it out to draw every winner again. |

Returns `{ giveaway, previous_winners }`.

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

Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

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

### List winners

`GET /giveaways/{id}/winners` · scope `giveaways:read`

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

Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

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

## Scheduled giveaways

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

`status` is one of:

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

### List scheduled giveaways

`GET /scheduled-giveaways` · scope `giveaways:read`

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

Query: `status` (Only schedules with this status: pending, launched, failed, recurring, paused or ended.). Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

Returns a page of scheduled giveaway objects.

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

Returns the scheduled giveaway object.

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

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

`end` is one of:

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

`recurrence` takes:

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

```bash
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"
    }
  }'
```

Returns the scheduled giveaway object.

### 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`.

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

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

Returns the scheduled giveaway object.

### 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`.

No body. Returns `{ id, deleted: true }`.

## Tasks and task types

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

```json
{
  "type": "youtube-subscribe",
  "config": {
    "url": "https://youtube.com/@scoplidrop",
    "verificationMethod": "timer-based"
  },
  "required": true,
  "points": 1
}
```

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

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

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

### List task types

`GET /task-types` · scope none

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: `category` (Only the task types of one category. One of social, discord, community, web, music, games, roblox, custom.)

Returns `{ data, next_cursor }` where each item is a task type object.

### Get a task type

`GET /task-types/{type}` · scope none

Returns one task type. An unknown type answers `not_found`.

Call it before you write a task of a type you have not used yet.

## Task templates

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

### List task templates

`GET /task-templates` · scope `templates:read`

Returns the task templates of the server, newest first.

Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

Returns a page of task template objects.

### Get a task template

`GET /task-templates/{id}` · scope `templates:read`

Returns one task template. A template of another server answers `not_found`.

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

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

```bash
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"
        }
      }
    ]
  }'
```

Returns the task template object.

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

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

Returns the task template object.

### Delete a task template

`DELETE /task-templates/{id}` · scope `templates:write`

Deletes the template for good. Giveaways already created from it keep their tasks.

No body. Returns `{ id, deleted: true }`.

## Economy

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.

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

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

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

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

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

Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

Each item is a balance object plus `rank` (The position by balance, starting at 1.)

### List transactions

`GET /economy/transactions` · scope `economy:read`

The transaction log, newest first.

Query: `user_id` (Only the transactions of this member.) Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

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

### 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: `period` (A rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Defaults to 30d.) Or `from` (The first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period.) with `to` (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.)

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

## Analytics

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: `period` (A rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Defaults to 30d.) Or `from` (The first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period.) with `to` (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.)

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

## Features

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` · scope none

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: `category` (Only the features of one category. One of tasks, running-giveaways, anti-cheat, growth, automation, engagement, analytics, integrations, teams.)

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

### Get a feature

`GET /features/{id}` · scope none

Returns one feature in full. An id outside the catalog answers `not_found`.

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

## Updates (changelog)

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` · scope none

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: `period` (A rolling period that ends now: 7d, 14d, 30d, 90d, 6m or 1y. Leave out period, from and to for the newest notes.) Or `from` (The first day of a custom range, written YYYY-MM-DD, in UTC. Send it with to, in place of period.) with `to` (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.) Paging: `limit` (Page size, 1 to 100. Defaults to 25.) and `cursor` (The `next_cursor` of the previous page. Leave it out for the first page.)

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

### Get an update

`GET /updates/{id}` · scope none

Returns one note in full. An id that is not a note answers `not_found`.

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

## 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. A required choice lists its values. Read `GET /task-types/{type}` for every allowed value, default and limit.

- `youtube-subscribe`: Follow on YouTube. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `youtube-like`: Like YouTube video. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `youtube-comment`: Comment YouTube video. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `discord-join`: Join Discord Server. Config: **`serverId`**, `inviteUrl`, `verificationMethod`.
- `x-follow`: Follow on X. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `x-like`: Like X post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `x-repost`: Repost on X. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `x-comment`: Comment X post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `x-post`: Post on X, premium plan. Config: **`postText`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `instagram-follow`: Follow on Instagram. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `instagram-like`: Like Instagram post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `instagram-comment`: Comment Instagram post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `instagram-repost`: Repost in Instagram story. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `instagram-tag-friends`: Tag friends in IG comment. Config: **`url`**, `friendCount`, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `facebook-follow`: Follow on Facebook. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `facebook-join-group`: Join Facebook group. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `facebook-like-post`: Like Facebook post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `facebook-comment`: Comment Facebook post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `facebook-watch`: Watch Facebook video. Config: **`url`**, `minTime`, **`verificationMethod`** (timer-based or video-code), `videoCodes`.
- `twitch-follow`: Follow on Twitch. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data or twitch-follow-system), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `twitch-subscribe`: Subscribe on Twitch. Config: **`url`**, `minTier`, **`verificationMethod`** (timer-based or additional-data or twitch-subscribe-system), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `discord-role-check`: Have Discord Role. Config: **`roleIds`**, `customNote`.
- `discord-role-assign`: Claim Discord Role. Config: **`roleId`**, `customNote`.
- `discord-voice-time`: Voice Channel Activity. Config: `minValue`, `aggregationMode`, `timeWindowDays`.
- `discord-message-count`: Message Activity. Config: `minValue`, `aggregationMode`, `timeWindowDays`.
- `discord-xp-level`: Reach XP/Level. Config: `requirementType`, `minValue`.
- `discord-member-since`: Time in Server, premium plan. Config: `memberSinceMode`, `minMemberDays`.
- `scoplidrop-giveaway-regular`: Giveaway Regular. Config: `minGiveaways`, `timeWindowDays`.
- `scoplidrop-play-minigames`: Play Minigames. Config: `minGames`, `gameType`, `timeWindow`, `minOpponents`.
- `website-visit`: Visit website. Config: **`url`**, `customNote`.
- `collect-email`: Provide Email, premium plan. Config: `customNote`.
- `tiktok-follow`: Follow on TikTok. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `tiktok-like`: Like TikTok video. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `tiktok-comment`: Comment TikTok video. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `tiktok-repost`: Repost TikTok video. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `telegram-join-group`: Join Telegram group. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `telegram-view-post`: View Telegram post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `kick-follow`: Follow on Kick. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `kick-subscribe`: Subscribe on Kick. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `kick-watch`: Watch Kick stream. Config: **`url`**, `minTime`, **`verificationMethod`** (timer-based or video-code), `videoCodes`.
- `pinterest-follow`: Follow on Pinterest. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `pinterest-visit`: Visit Pinterest page. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `reddit-visit-subreddit`: Visit subreddit. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `reddit-follow-subreddit`: Follow subreddit. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `reddit-follow-user`: Follow Reddit user. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `spotify-follow-artist`: Follow Spotify artist. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `spotify-follow-playlist`: Follow Spotify playlist. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `spotify-listen-song`: Listen to Spotify song. Config: **`url`**, `minTime`, `verificationMethod`.
- `spotify-save-song`: Save Spotify song. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `spotify-pre-save`: Pre-save on Spotify. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `bluesky-follow`: Follow on Bluesky. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `bluesky-like`: Like Bluesky post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `bluesky-repost`: Repost on Bluesky. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `snapchat-follow`: Follow on Snapchat. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `linkedin-follow-company`: Follow LinkedIn company. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `linkedin-follow-user`: Follow LinkedIn user. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `linkedin-connect-user`: Connect to LinkedIn user. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `youtube-watch`: Watch YouTube video. Config: **`url`**, `minTime`, **`verificationMethod`** (timer-based or video-code), `videoCodes`.
- `tiktok-watch`: Watch TikTok video. Config: **`url`**, `minTime`, **`verificationMethod`** (timer-based or video-code), `videoCodes`.
- `twitch-watch`: Watch Twitch stream. Config: **`url`**, `minTime`, **`verificationMethod`** (timer-based or video-code), `videoCodes`.
- `instagram-watch`: Watch Instagram Reel. Config: **`url`**, `minTime`, **`verificationMethod`** (timer-based or video-code), `videoCodes`.
- `scoplidrop-topgg-upvote`: Upvote ScopliDrop on Top.gg. Config: none.
- `scoplidrop-lootbox-open`: Open the lootbox. Config: none.
- `scoplidrop-listing-upvote`: Upvote this giveaway on ScopliDrop. Config: none.
- `soundcloud-listen-song`: Listen to SoundCloud song. Config: **`url`**, `minTime`, `verificationMethod`.
- `soundcloud-like-song`: Like SoundCloud song. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `soundcloud-repost-song`: Repost SoundCloud song. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `soundcloud-follow-artist`: Follow SoundCloud artist. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `patreon-visit`: Visit Patreon page. Config: **`url`**.
- `meta-quest-wishlist`: Add to Meta Wishlist. Config: **`url`**, `verificationMethod`.
- `steam-wishlist`: Wishlist on Steam, premium plan. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `steam-follow-game`: Follow a game on Steam. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `steam-join-group`: Join a Steam group. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `roblox-join-community`: Join a Roblox Community. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data or roblox-api-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `minRank`, `minAccountAgeDays`.
- `roblox-feature-community`: Feature a Roblox Community on Your Profile. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data or roblox-api-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `minAccountAgeDays`.
- `roblox-badge`: Earn a Roblox Badge. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data or roblox-api-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `badgeWindow`, `minAccountAgeDays`.
- `roblox-own-item`: Own a Roblox Game Pass or Item. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data or roblox-api-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `extraItems`, `minAccountAgeDays`.
- `roblox-profile-text`: Add Text to Your Roblox Profile. Config: **`profileText`**, `profilePlace`, **`verificationMethod`** (timer-based or additional-data or roblox-api-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `minAccountAgeDays`.
- `roblox-forum-comment`: Comment on a Roblox Forum Post. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data or roblox-api-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `commentWindow`, `minAccountAgeDays`.
- `roblox-play-game`: Play a Roblox Game. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `roblox-follow-game`: Follow a Roblox Game. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `roblox-favorite-game`: Favorite a Roblox Game. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `roblox-like-game`: Like a Roblox Game. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `roblox-follow-user`: Follow on Roblox. Config: **`url`**, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `discord-primary-guild`: Set Discord Server Tag, premium plan. Config: **`serverId`**, **`serverName`**, `verificationMethod`.
- `combo-task`: Combo Task, premium plan. Config: **`platform`** (youtube or x or tiktok or facebook), **`actions`**, **`url`**, `minTime`, **`verificationMethod`** (timer-based or additional-data), `proofType`, `screenshotCount`, `screenshotInstructions`.
- `custom-task`: Custom Task, business plan. Config: **`customName`**, `iconId`, `customNote`, **`verificationMethod`** (timer-based or direct-data-collection or additional-data or external-app-system), `proofType`, `screenshotCount`, `screenshotInstructions`, `taskUrl`, `verifiedAction`, `customFields`.

## AI assistants (MCP)

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. The MCP server is at `https://t.scoplidrop.com/mcp`.

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.
