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 across 396 sites, 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, 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 vote toast 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/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 vote 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: deliver a set number of votes to 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 vote 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-vote 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 the username that voted
• POST/orders/averageAPI keyAverage delivery across several campaigns
• GET/api/logs/{id}/filtered-graphJWTFiltered time series

Vote & proxy profiles#

A vote profile is a named list of usernames a campaign votes with. 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 vote profiles
• GET/advanced/profile/get/{id}API keyOne vote profile
• POST/advanced/profile/createAPI keyCreate a vote profile, or overwrite one by id
• DELETE/advanced/profile/delete/{id}API keyDelete a vote 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 authenticate voters through Discord. 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/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/. 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 votes; 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 votes.
// 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.