API v2 — documentation

1. Getting started

Three steps to your first request: get an API key in the dashboard, send a request to the single /api/v2 address with the required key and action parameters, then parse the JSON response. The account currency is Russian rubles (RUB).

Base URL

All methods are called relative to the base URL. The same address is returned in the api_url field of GET /api/config.

Your first request — check the balance:

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=balance

2. Authentication

Authentication uses a personal API key in the form bc_live_…. The key is issued in the dashboard after sign-up and is sent with every request in the key parameter.

The key can be regenerated in the dashboard (the old one then stops working). Keep it secret: it grants full access to the account’s orders and balance.

Where to get the key:

1. Sign up and log in to the dashboard.
2. Open the API-key section — it shows a key like bc_live_xxxxxxxxxxxxxxxxxx.
3. If needed, click “Regenerate” to replace the key.

3. Request and response format

All methods are called at a single /api/v2 address. A request can be sent either as GET (query-string parameters) or POST (body in application/x-www-form-urlencoded or application/json). Parameters required for every request: key (the API key) and action (the method name).

The response is always JSON. A successful response contains the method’s fields; an error is returned as an object with an error field describing the reason. Monetary values are in rubles (account currency RUB), responses include a currency field; numeric fields (rate, min, max, charge, start_count, remains) are returned as strings. The account level discount (based on your order volume over the last 60 days) is applied automatically to the actual charge on add — the same in the dashboard and via the API; the rate in services is the base price before the discount.

The panel UI may additionally show amounts in US dollars at the current rate — this is a reference equivalent for convenience; all calculations and charges are always in rubles. The rate and rounding are approximate, and the API does not guarantee accounting-grade precision of the displayed $ equivalent.

4. Methods

The single endpoint supports the actions below. The “Status” column shows each method’s real readiness; experimental and planned capabilities are listed in the “Limitations” section.

5. Method reference

Full description of each method: parameters, an example request (curl) and the actual response format. Identifiers in the examples are illustrative.

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=services

[
  {
    "service": 1001,
    "name": "Instagram Followers [Refill 30D] [Max: 100K]",
    "type": "Default",
    "category": "Instagram — Followers",
    "rate": "130.5",
    "min": "115",
    "max": "100000",
    "refill": true,
    "cancel": true,
    "dripfeed": true,
    "currency": "RUB",
    "available": true
  },
  {
    "service": 1002,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram — Likes",
    "rate": "48.0",
    "min": "313",
    "max": "50000",
    "refill": false,
    "cancel": true,
    "dripfeed": true,
    "currency": "RUB",
    "available": true
  },
  {
    "service": 1003,
    "name": "YouTube Views (broken data)",
    "type": "Default",
    "category": "YouTube — Views",
    "rate": "90.0",
    "min": "1000",
    "max": "20",
    "refill": false,
    "cancel": true,
    "dripfeed": true,
    "currency": "RUB",
    "available": false
  }
]

# Default
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add \
  -d service=1001 \
  -d link=https://instagram.com/example \
  -d quantity=1000

# Drip-feed (repeats) — runs + interval
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add -d service=1002 \
  -d link=https://youtube.com/watch?v=xxxx \
  -d quantity=1000 -d runs=10 -d interval=30

# Custom Comments (planned) — comments, one per line
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add -d service=1001 \
  -d link=https://instagram.com/p/xxxx \
  --data-urlencode $'comments=Great post!\nFire\nLove it'

# Mentions (planned) — usernames
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=add -d service=1001 \
  -d link=https://instagram.com/p/xxxx \
  -d usernames=user_a,user_b,user_c

# success — the created order ID
{ "order": 23501 }

# error (insufficient balance)
{ "error": "Not enough funds on the balance" }

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=status \
  -d order=23501

{
  "charge": "15.32",
  "start_count": "1273",
  "status": "Pending",
  "remains": "1000",
  "currency": "RUB"
}

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=status \
  -d orders=23501,23502

{
  "23501": { "charge": "15.32", "start_count": "1273", "status": "Completed", "remains": "0", "currency": "RUB" },
  "23502": { "error": "Incorrect order ID" }
}

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=balance

{
  "balance": "34.68",
  "currency": "RUB"
}

# single order
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=refill \
  -d order=23501

# several orders
curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=refill \
  -d orders=23501,23502

# single order (order=ID) — refill identifier (= order ID)
{ "refill": 23501 }

# several (orders=ID,ID) — array per order
[
  { "order": "23501", "refill": 23501 },
  { "order": "23502", "error": "Refill is not available for this order" }
]

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=refill_status \
  -d refill=23501

{ "status": "Completed" }

# refill still in progress
{ "status": "In progress" }

curl -s "https://api.papasmm.com/api/v2" \
  -d key=bc_live_xxxxxxxxxxxxxxxxxx \
  -d action=cancel \
  -d orders=23501,23502

[
  { "order": "23501", "cancel": 1 },
  { "order": "23502", "cancel": { "error": "Order can not be canceled" } }
]

6. Limitations & experimental

Below is what is implemented partially or is only planned for now. Do not rely on these as finished features.

• Planned Custom Comments. The custom-comments order type (comments parameter in add) is not implemented yet — add accepts Default and Drip-feed only.
• Planned Mentions. The mentions order type (usernames parameter) is not implemented yet.
• basic refill_status. Returned in a simplified form: only Completed or In progress. There is no detailed refill status yet.
• Planned Refill identifier. The refill field currently equals the order ID; separate refill-request IDs are planned.
• Planned Idempotency for add. There is no double-order protection: repeating add with the same parameters creates a new order and charges again. An idempotency key is planned.
• Timeout behavior. If an add request ended with a network timeout, the order may already have been created on the server. Do not retry blindly: first check balance and the latest status, and only then retry if needed.

7. Errors

Errors are returned as an object with an error field describing the reason. Below are the actual error messages returned by API v2.

8. Changelog

A short note on the public API versions.

• v2 — current. Public key API: services, add (Default, Drip-feed), status (single and multiple), balance, refill, cancel. Account currency RUB, numeric values as strings. refill_status — basic.
• v2.1 — planned. Custom Comments and Mentions order types, an idempotency key for add, separate refill-request IDs and a detailed refill_status.