API

Endpoint and authentication

Getting your key: in the dashboard, open Tools → API. A key is created automatically the first time you open that page. From there you can reveal, copy or regenerate it. When you regenerate, the old key stops working immediately.

API orders follow the same balance and validation rules as orders placed in the dashboard. GET is handy for quick tests, but it puts your key into URLs and server logs, so prefer POST in production.

Actions overview

services: list services

curl -X POST https://better-social.pro/api/v2 \
  -d key=YOUR_API_KEY \
  -d action=services

Returns an array with one object per available service:

Example response (illustrative values)

[
  {
    "service": 101,
    "name": "TikTok Live Likes",
    "type": "Default",
    "category": "TikTok Live",
    "rate": "1.5000",
    "min": "100",
    "max": "100000",
    "refill": false,
    "cancel": false,
    "dripfeed": false,
    "needs_custom_text": false
  }
]

add: place an order

The charge is rate × quantity ÷ 1000 and is taken from your balance. If your balance is too low, the order is rejected.

curl -X POST https://better-social.pro/api/v2 \
  -d key=YOUR_API_KEY \
  -d action=add \
  -d service=101 \
  -d link=@username \
  -d quantity=500

Response

{"order": 123456, "charge": "0.7500"}

Use the returned order value with status, refill and cancel. Manual services return an order ID string and "manual": true, for example {"order": "3f2c...", "manual": true, "charge": "5.0000"}.

Custom comments (JSON body)

curl -X POST https://better-social.pro/api/v2 \
  -H "Content-Type: application/json" \
  -d '{"key":"YOUR_API_KEY","action":"add","service":202,"link":"@username","comments":"Great stream!\nHello from Podgorica"}'

status: check an order

curl -X POST https://better-social.pro/api/v2 \
  -d key=YOUR_API_KEY \
  -d action=status \
  -d order=123456

Response

{
  "charge": "0.7500",
  "start_count": null,
  "status": "In progress",
  "remains": "120",
  "currency": "USD",
  "order": 123456
}

• status comes from the delivery provider (for example Pending, In progress, Completed, Partial, Canceled).
• remains is the provider's undelivered count, or null if unknown. start_count is currently always null.
• An unknown order ID returns {"error": "not found"}.
• Each status call asks the provider for a fresh status, so please don't poll in a tight loop.

multi_status: check several orders

Send orders as a comma-separated list (a | separator also works). The response is an object keyed by the IDs you sent. status with several IDs in orders behaves the same way. status with a single ID returns a single object.

curl -X POST https://better-social.pro/api/v2 \
  -d key=YOUR_API_KEY \
  -d action=multi_status \
  -d orders=123456,123457

Response

{
  "123456": {"charge": "0.7500", "start_count": null, "status": "Completed", "remains": "0", "currency": "USD", "order": 123456},
  "123457": {"error": "not found"}
}

balance: check your balance

curl "https://better-social.pro/api/v2?key=YOUR_API_KEY&action=balance"

Response

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

refill and cancel

Send order (one ID) or orders (comma-separated). Your request is forwarded to the delivery provider, and the provider's answer is returned unchanged. For several IDs, it comes back as an object keyed by your IDs. Unknown IDs return {"error": "not found"}.

curl -X POST https://better-social.pro/api/v2 \
  -d key=YOUR_API_KEY \
  -d action=refill \
  -d order=123456

Whether a refill or cancel is possible depends on the service (see the refill and cancel flags in services). Our cancellation policy still applies: orders that have started can't be cancelled.

Errors

Errors use HTTP status codes with a JSON body. Most look like {"detail": {"error": "message"}}. Some use a plain string, such as {"detail": "Invalid API key"}. Always check the HTTP status code.

Inside status, multi_status, refill and cancel results, a problem with a single order is reported as {"error": "..."} for that order, with HTTP 200.

Python example

import os
import requests

API = "https://better-social.pro/api/v2"
KEY = os.environ["BETTER_SOCIAL_API_KEY"]  # keep the key out of your code

def call(action, **params):
    r = requests.post(API, data={"key": KEY, "action": action, **params}, timeout=30)
    r.raise_for_status()
    return r.json()

print(call("balance"))
order = call("add", service=101, link="@username", quantity=500)
print(call("status", order=order["order"]))

Best practices

• Store the key in an environment variable or secret manager, never in front-end code.
• Regenerate the key if you think it has been exposed, or when someone with access leaves your team.
• Read services regularly. Prices and availability change.
• Respect the one-order-per-link rule. See Orders.
• Poll statuses at a reasonable interval, for example every few minutes, ideally with multi_status.