API documentation

action=services

Lists every site you can order on, with its current rate and limits. Use the `service` id in your add calls.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=services"

[
  {
    "service": 9,
    "name": "arena-top100.com 1000 upvotes",
    "type": "Default",
    "category": "Votes",
    "rate": 15,
    "min": 1,
    "max": 50000,
    "refill": false,
    "cancel": true
  }
]

`rate` is tokens per 1,000 actions. `min` is 1 and `max` is 50000 for every service.

action=add

Creates a campaign and immediately deducts its cost from your balance.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=9" \
  -d "link=https://arena-top100.com/index.php?a=in&u=yourserver" \
  -d "quantity=1000" \
  -d "interval=60"

{
  "order_id": 184223
}

action=status

Returns progress for one or more orders. Pass a single id for a flat object, or a comma-separated list.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=status" \
  -d "orders=184223"

{
  "charge": 13.5,
  "start_count": 0,
  "status": "Completed",
  "remains": 1000,
  "currency": "USD"
}

With several ids the response is keyed by order id, and unknown or foreign orders return an error entry rather than failing the whole request.

{
  "184223": { "charge": 13.5, "start_count": 0, "status": "Completed", "remains": 1000, "currency": "USD" },
  "184224": { "error": "Incorrect order ID" }
}

`status` and `cancel` accept at most 100 order ids per call. Batch rather than looping — one call with 100 ids is far cheaper for both sides than 100 calls.

action=balance

Returns your remaining token balance.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=balance"

{
  "balance": 528.41,
  "currency": "USD"
}

action=cancel

Stops an order and refunds the unspent remainder to your balance. Completed orders cannot be cancelled.

curl -X POST https://backend.toplistbot.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=cancel" \
  -d "orders=184223,184224"

[
  { "order": "184223", "cancel": 1, "refund": 4.5 },
  { "order": "184224", "cancel": { "error": "Incorrect order ID" } }
]

Catalog & discovery#

Public, no credential needed. getAllWebsites is the endpoint to start from — it carries the id, price, hourly ceiling and accept rate you need to price and shape an order.

• GET/orders/getAllWebsitesPublicThe full catalog — every site with rates, limits and metadata
• GET/orders/getAllBasicWebsitesDetailsPublic20 random site names, for widgets and autocompletes
• POST/orders/getWebsiteDetailsByNamePublicOne site by its exact name
• POST/products/getSuggestionsPublicSites related to a set of ids
• GET/products/demand?days=30PublicHow much each site has been ordered recently
• GET/products/tokensPublicToken packages you can buy
• POST/products/suggestAPI keyAsk us to list a new site
• GET/api/news/timelinePublicProduct changelog

curl "https://backend.toplistbot.com/orders/getAllWebsites"

Ask for less

The full catalog is about 665 KB, and two fields you will never order with account for half of it: a stored popularity blob and the marketing description. Project down to the ordering fields and drop inactive sites and it becomes about 40 KB.

# The whole catalog is ~665 KB across 396 sites.
# Projected to what you actually order with: ~40 KB.
curl -s "https://backend.toplistbot.com/orders/getAllWebsites" \
  | jq '[.[]
      | select(.active == 1)
      | {id, name, price_per_1000, max_per_hour, accept_rate, subscribeable}]'

Account & sessions#

Registration needs a browser: it is gated by a Cloudflare challenge. Sign up once at app.toplistbot.com, then automate everything after it.

• POST/api/auth/registerPublicCreate an account — browser only, gated by a captcha
• POST/api/auth/loginPublicExchange credentials for a JWT
• POST/api/auth/refreshJWTIssue a fresh JWT from an expiring one
• POST/api/auth/logoutJWTInvalidate the current JWT
• GET/api/auth/user-profileJWTThe signed-in account, with balance and API key
• GET/api/userJWTThe same user object, under a shorter path
• GET/api/api_tokenAPI keyResolve an API key to its owner — use it to validate a key
• POST/api/auth/reset-api-keyJWTRotate your API key; the old one dies immediately
• POST/api/auth/fingerprintJWTRecord a browser fingerprint against the account
• POST/api/auth/ipJWTRecord the account's current IP
• POST/api/auth/forgot-passwordPublicEmail a reset link, valid 60 minutes
• POST/api/auth/reset-passwordPublicSet a new password with the emailed token

Two-factor & sign-in#

Two-factor protects the password login. It does not apply to API keys, which is why a key is the better credential for unattended work.

• POST/api/2fa/enableJWTStart enrolment — returns the secret, QR URL and recovery codes
• POST/api/2fa/verifyJWTConfirm a six-digit code and switch two-factor on
• POST/api/2fa/disableJWTSwitch two-factor off
• POST/api/account/verification/requestJWTEmail a verification link to the signed-in address
• GET/api/account/verification/confirm?token=PublicRender the confirmation page — writes nothing
• POST/api/account/verification/confirmPublicCommit the verification
• GET/api/auth/googlePublicStart Google sign-in
• GET/api/auth/google/callbackPublicGoogle sign-in callback
• GET/api/auth/discordPublicStart Discord sign-in
• GET/api/auth/discord/callbackPublicDiscord sign-in callback

Preferences & alerts#

Email and notification switches, your webhook, and the account's alert feed.

• GET/api/user/email-preferencesJWTMarketing email opt-in state
• POST/api/user/email-preferencesJWTChange it
• GET/api/user/notification-preferencesJWTLive delivery notification preference
• POST/api/user/notification-preferencesJWTChange it — must be a real JSON boolean
• GET/api/user/alerts?limit=20JWTAccount alerts, newest first, paged on ?before
• POST/api/user/alerts/readJWTMark an alert read
• POST/api/user/alerts/dismissJWTDismiss an alert
• GET/api/user/webhooksJWTYour webhook: address, events and delivery health
• POST/api/user/webhooksJWTSave the address, the events and the on/off switch
• POST/api/user/webhooks/testJWTSend one test event now and report what your server answered
• GET/api/user/webhooks/deliveries?limit=25JWTWebhook delivery log, newest first, paged on ?before
• GET/api/email/unsubscribe?token=PublicOne-click unsubscribe from an emailed token

Campaigns#

Create campaigns, steer them while they run, and wind them down. This is the core of the platform API.

• GET/orders/getAllAPI keyYour campaigns, newest first, with their sites joined in
• GET/orders/get/{id}API keyOne campaign
• POST/orders/checkoutAPI keyCreate campaigns and charge the balance
• POST/orders/updateAPI keyEdit a campaign
• POST/orders/pauseAPI keyPause a running campaign
• POST/orders/unpauseAPI keyResume a paused campaign
• POST/orders/archiveAPI keyArchive a campaign
• POST/orders/unarchiveAPI keyRestore an archived campaign
• PATCH/orders/updateLimitAPI keySet or clear the daily action cap

POST /orders/checkout

The body is a top-level JSON array of cart lines, not an object. Every line is one campaign. The whole cart is validated before anything is charged, and the charge and the inserts are one transaction — a checkout either happens completely or not at all.

A fixed-quantity line

The ordinary case: a set number of actions for one URL.

curl -X POST "https://backend.toplistbot.com/orders/checkout?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": 9,
      "amount": 1000,
      "ownName": "https://arena-top100.com/index.php?a=in&u=yourserver",
      "custom_max_per_hour": 60
    }
  ]'

200 OK
Successfully purchased with token balance

A subscription line

For sites whose `subscribeable` flag is 1. Priced from the site's subscription_price_1d multiplied by the number of days and the tier discount — Weekly is 0.90, Monthly is 0.80, anything else 1.00. The delivered quantity is derived server-side from the site's own subscription_speed, so nothing you send changes it.

[
  {
    "type": "subscription",
    "website": { "id": 9 },
    "subscription_days": 30,
    "tier": { "name": "Monthly" },
    "url": "https://arena-top100.com/index.php?a=in&u=yourserver"
  }
]

Responses

• 200Every line was created and the balance was charged. The body is plain text.
• 400The body was not valid JSON.
• 402Not enough tokens. The message names the amount needed, and nothing was charged.
• 422One or more lines are wrong. Nothing was charged.
• 429The identical cart was submitted within the last 60 seconds. Retry after the stated wait.

A 422 names the offending line: errors are keyed items.[index].[field], so a cart with three bad lines takes one round trip to fix rather than three.

{
  "errors": {
    "items.2.amount": ["Enter 0 or more votes; a negative amount is not allowed."]
  }
}

POST /orders/update

`id` is required; send only the fields you are changing. Subscription orders cannot be modified.

curl -X POST "https://backend.toplistbot.com/orders/update?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"amount_to_do":2000,"custom_name":"EU launch"}'

Daily cap

`type: "delete"` clears the cap. `max_votes_per_day` is still required by the validator in that case — send any integer.

curl -X PATCH "https://backend.toplistbot.com/orders/updateLimit?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":184223,"max_votes_per_day":500,"type":"set"}'

Logs & analytics#

Delivery data, per action and aggregated. These read a separate logs database and are slower than the rest of the API — poll them at minutes, not seconds.

• GET/orders/logs/{id}API keyPer-action delivery log for a campaign
• GET/orders/graph/{id}API keyTime series for one campaign, ready to chart
• GET/api/orders/graph/summaryJWTOne series across every campaign
• GET/orders/grouped/usernames/{id}API keyDeliveries grouped by username
• POST/orders/averageAPI keyAverage delivery across several campaigns
• GET/api/logs/{id}/filtered-graphJWTFiltered time series

Username & proxy profiles#

A username profile is a named list of usernames a campaign uses. A proxy profile is a named country allowlist for the IPs it uses. Attach either to a campaign with username_profile_id or proxy_profile_id on /orders/update.

• GET/advanced/profile/getAPI keyYour username profiles
• GET/advanced/profile/get/{id}API keyOne username profile
• POST/advanced/profile/createAPI keyCreate a username profile, or overwrite one by id
• DELETE/advanced/profile/delete/{id}API keyDelete a username profile
• GET/advanced/profile/proxy/getAPI keyYour proxy profiles
• GET/advanced/profile/proxy/get/{id}API keyOne proxy profile
• POST/advanced/profile/proxy/createAPI keyCreate a proxy profile, or overwrite one by id
• DELETE/advanced/profile/proxy/delete/{id}API keyDelete a proxy profile

Discord tokens#

For toplists that require a Discord sign-in. Adding the same token twice is rejected as a duplicate.

• GET/api/discord-tokensJWTYour Discord tokens
• POST/api/discord-tokensJWTAdd a token
• GET/api/discord-tokens/statsJWTUsage counts across your tokens
• GET/api/discord-tokens/{id}JWTOne token
• PATCH/api/discord-tokens/{id}JWTChange a token or its enabled flag
• DELETE/api/discord-tokens/{id}JWTRemove a token
• PUT/api/discord-tokens/{id}/toggleJWTFlip a token between enabled and disabled

Billing & payments#

Buying tokens always ends on a hosted payment page, so topping up cannot be fully headless. Everything after the top-up can be.

• GET/invoices/getAPI keyBilling history
• GET/api/subscriptions/subscriptionsJWTActive subscriptions
• GET/products/tokensByUserAPI keyToken packages priced for your account
• POST/company/getAPI keyYour billing address
• POST/company/createAPI keySet it — country, region, city, address, postalCode
• GET/api/stripe/checkout?product_id=JWTA Stripe Checkout URL for a token package
• GET/api/stripe/subscription?plan=JWTA Stripe Checkout URL for a plan
• GET/api/stripe/portalJWTA Stripe billing-portal URL
• GET/api/stripe/documentsJWTStripe invoices and receipts
• GET/coinpayments/checkoutAPI keyA crypto checkout URL

Saved cart#

The dashboard's cart, persisted server-side so it survives a device change. You do not need it to place orders — /orders/checkout takes the cart inline.

• GET/api/cartJWTThe saved cart
• PUT/api/cartJWTReplace it
• POST/api/cartJWTReplace it — same as PUT
• DELETE/api/cartJWTEmpty it

Internal surfaces#

These exist for Stripe, the job scheduler and the signup anti-abuse challenge. They are authenticated by shared secrets or signatures and are not part of the integration surface — listed here only so the inventory is complete.

• POST/api/stripe/webhookStripe payment events — signature authenticated
• POST/api/jobs/tickRuns due background jobs — shared-secret authenticated
• POST/api/internal/vote-eventsVote events from the voter — shared-secret authenticated
• POST/api/pow/challengeSignup proof-of-work challenge
• POST/api/logs/updateEmail activity tracker
• POST/api/order/{email}Places an order on another account — admin allowlist only
• GET/reset-password/{token}The old server-rendered password reset page, kept for emailed links
• GET/PublicHealth check

The site object#

Returned by /orders/getAllWebsites and /orders/getWebsiteDetailsByName, and joined into each campaign as `website`.

The fields omitted here drive the dashboard's own interface. Read them if you like, but they are not part of the integration contract and may change without notice.

The campaign object#

Returned by /orders/getAll and /orders/get/:id. Note what is missing: there is no status field.

The fields omitted here drive the dashboard's own interface. Read them if you like, but they are not part of the integration contract and may change without notice.

Is it running? Is it finished?#

A campaign has no status field, so you derive its state from four columns. Evaluate these in order and take the first match.

Progress and refunds#

amount_to_do counts accepted actions; amount_done counts submissions. Only accept_rate percent of submissions are accepted, so the two are in different units and subtracting one from the other directly is wrong.

// accept_rate arrives as a STRING, and it is per-site, not global.
const rate = Number(order.website.accept_rate)

// amount_done counts SUBMISSIONS; amount_to_do counts ACCEPTED actions.
// Convert before comparing them.
const delivered = order.amount_done * rate / 100
const remaining = Math.max(order.amount_to_do - delivered, 0)
const percent   = 100 * delivered / order.amount_to_do

// What cancelling right now would put back on your balance:
const refund    = (remaining / 1000) * order.website.price_per_1000

The same arithmetic prices a cancellation: the refund is the unspent remainder at the site's list price, so you can tell what stopping a campaign is worth before you commit to it.

Setting one up#

Four steps in the dashboard, and nothing to install.

1. 1

   Open the Webhook card

   In the dashboard, go to Account and open the Notifications tab.

2. 2

   Paste your address

   The URL of the endpoint on your server that should receive events. It must start with https:// and be reachable from the internet.

3. 3

   Choose your events

   Votes that went through and votes that failed are on by default. Vote started is off; switch it on only if you act on it.

4. 4

   Save, then send a test

   The address is checked when you save, and you are told straight away if it cannot be found or points at a private network. Then press Send test: a test event goes out at once, and the card shows what your server answered.

Over the API

The same settings are available over the platform API with a JWT. An API key cannot change them: the key is for running campaigns, and it must not be able to redirect your account's events somewhere else.

curl -X POST https://behind.toplistbot.com/api/user/webhooks \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/toplistbot/3f9c1a7e5b2d",
    "enabled": true,
    "events": ["vote.succeeded", "vote.failed"]
  }'

{
  "available": true,
  "webhook": {
    "url": "https://example.com/hooks/toplistbot/3f9c1a7e5b2d",
    "enabled": true,
    "events": ["vote.succeeded", "vote.failed"],
    "failing": false,
    "retry_at": null,
    "last_ok_at": null,
    "last_error": null,
    "last_error_at": null,
    "created_at": "2026-10-06T09:12:44.000000Z",
    "updated_at": "2026-10-06T09:12:44.000000Z"
  },
  "events": ["vote.started", "vote.succeeded", "vote.failed"],
  "default_events": ["vote.succeeded", "vote.failed"]
}

A test is sent exactly once and never retried. The response tells you whether it arrived and what your server answered.

curl -X POST https://behind.toplistbot.com/api/user/webhooks/test \
  -H "Authorization: Bearer YOUR_JWT"

{
  "delivered": false,
  "http_status": 500,
  "error": "Your server had an error (HTTP 500).",
  "delivery": { "id": 1874, "event": "webhook.test", "status": "failed", "...": "..." }
}

Events#

Every request carries exactly one event.

Payload and headers#

Each event is a POST request with a small JSON body.

POST /hooks/toplistbot/3f9c1a7e5b2d HTTP/1.1
Content-Type: application/json
User-Agent: Toplistbot-Webhooks/1.0 (+https://toplistbot.com)
X-Toplistbot-Event: vote.succeeded
X-Toplistbot-Delivery: 1873

{
  "id": 1873,
  "event": "vote.succeeded",
  "created_at": "2026-10-06T09:12:44.123Z",
  "order_id": 184223,
  "vote_job_id": "7f3c2a9e-1b4d-4c8e-9a2f-5d6e7f8a9b0c",
  "site": "https://arena-top100.com/index.php?a=in&u=yourserver",
  "username": "PlayerOne"
}

The key facts are repeated in the headers, so you can route a request without parsing its body.

Receiving events and retries#

Answer with any 2xx status within 5 seconds. Do the slow work, such as database writes or rewarding a player, after you have answered or in a queue of your own.

• 2xxDelivered. Nothing more happens.
• 3xxRedirects are not followed. The event counts as failed and is not retried, so save the final address instead.
• 4xxRefused. The event is marked failed and not retried, because sending it again would get the same answer. 408, 425 and 429 are the exception: those are retried.
• 5xxRetried, and so are timeouts, refused connections and invalid certificates.

When your server fails, we stop sending to it straight away instead of knocking on a closed door. New events are queued, and we try again after 1 minute, then 2, 4, 8 and so on, up to an hour apart. Retries run every 5 minutes, so a wait is rounded up to the next run. As soon as your server answers again, the queue is sent oldest first. Pressing Send test after you have fixed your server releases the queue at once.

An event that still could not be delivered after 24 hours is marked failed. Switching the webhook off discards everything that is still queued.

A minimal receiver: answer first, skip duplicates, then do the work.

import express from 'express'

const app = express()
const seen = new Set() // use your database in production

app.post('/hooks/toplistbot/3f9c1a7e5b2d', express.json(), (req, res) => {
  // 1. Answer straight away. Anything slower than 5 seconds is a failure.
  res.sendStatus(204)

  // 2. Skip duplicates. A retry carries the same id.
  const event = req.body
  if (seen.has(event.id)) return
  seen.add(event.id)

  // 3. Now do the work.
  if (event.event === 'vote.succeeded') {
    rewardPlayer(event.username, event.order_id)
  }
})

app.listen(3000)

Delivery log#

Every event we send is logged with the status your server answered and, for a failure, the reason. The dashboard shows the log under the Webhook card. Over the API it comes newest first, 25 per page by default and at most 100. Delivered events are kept for 7 days and failed ones for 30.

curl "https://behind.toplistbot.com/api/user/webhooks/deliveries?limit=25" \
  -H "Authorization: Bearer YOUR_JWT"

# next page: pass the id of the last delivery you received
curl "https://behind.toplistbot.com/api/user/webhooks/deliveries?limit=25&before=1850" \
  -H "Authorization: Bearer YOUR_JWT"

{
  "deliveries": [
    {
      "id": 1873,
      "event": "vote.succeeded",
      "order_id": 184223,
      "status": "delivered",
      "attempts": 1,
      "http_status": 204,
      "error": null,
      "created_at": "2026-10-06T09:12:44.000000Z",
      "delivered_at": "2026-10-06T09:12:44.000000Z",
      "payload": { "id": 1873, "event": "vote.succeeded", "...": "..." }
    }
  ],
  "has_more": true,
  "available": true
}

Security#

• HTTPS only. Events are never sent over an unencrypted connection.
• The address must be public. Addresses on private or local networks are refused when you save, and again every time we send, including a domain that is later pointed at one.
• No user name or password in the address. Use a secret path instead.
• Saving is limited to 20 times a minute and Send test to 5 times a minute.