REST API v2

Overview

This is the surface an AI agent drives. Every call is one verb chosen by action, so an agent searches the catalog, reads back the rate and limits, then acts, search-then-act, with the price confirmed before any money moves. The MCP server and CLI wrap these same calls; this page is the raw protocol underneath.

The API follows the widely adopted SMM API v2 shape, so existing panel software, scripts, and agent integrations work with minimal changes. Every operation goes through a single endpoint and picks the verb with the action parameter. Responses are JSON. Easy for a script or an LLM to parse and chain.

Endpoint

POST https://api.socialgo.com/api/v2

Authentication

Auth is per request, no session, no handshake, which is exactly what makes it callable by an agent. Send your secret key on every call. Find and rotate it in the dashboard under Account → API. Treat the key like a password: keep it server-side, never in client code or an agent prompt.

Request format

Send application/x-www-form-urlencoded form parameters over POST. Every response is JSON. Two parameters are on every call:

• key: your API key (required)
• action: the verb to run (required)

Error format

On failure the response carries an error field with a human-readable message, and the HTTP status reflects the problem (e.g. 400 bad request, 401 invalid key). One predictable shape, so a script or agent can branch on it without guessing.

{
  "error": "Incorrect request"
}

Actions

Each verb does one job. An agent chains them in order: services to find what to buy, add to buy it, status to track it. The read calls (services, status, balance) let it confirm price and funds before the write calls (add, refill, cancel) spend anything.

1. List services

The catalog an agent reads first: every service it can order, with the service ID, category, rate (price per 1000), and min/max quantities. It uses the returned service IDs to place orders, and the rate to confirm cost before spending.

Request

key=YOUR_API_KEY
action=services

Response

[
  {
    "service": 1,
    "name": "Instagram Followers",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.90",
    "min": "50",
    "max": "10000",
    "refill": true,
    "cancel": true
  },
  {
    "service": 2,
    "name": "Instagram Likes",
    "type": "Default",
    "category": "Instagram",
    "rate": "0.40",
    "min": "10",
    "max": "20000",
    "refill": false,
    "cancel": true
  }
]

2. Add order

The write call. Places an order for one service. Pass the service ID, the target link, and the quantity. The response returns the new order ID to track. An agent runs this only after it has confirmed the rate and limits.

Parameters

• service: service ID from the service list
• link: the URL of the post / profile / channel
• quantity: number of units to deliver

Request

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000

Response

{
  "order": 23501
}

3. Add order, drip-feed

Splits one order into smaller deliveries spread over time, for a steadier curve. Set runs (how many deliveries) and interval (minutes between each). Total delivered is quantity × runs. The math an agent uses to size a campaign without you doing it by hand.

Additional parameters

• runs: number of delivery runs
• interval: minutes between each run

Request

key=YOUR_API_KEY
action=add
service=1
link=https://instagram.com/example
quantity=1000
runs=10
interval=60

Response

{
  "order": 23502
}

4. Order status

Returns the current state of one order: charge, start count, status, remaining quantity, and currency. This is how an agent watches an order without you refreshing the dashboard, and how it spots a drop worth flagging for refill.

Request

key=YOUR_API_KEY
action=status
order=23501

Response

{
  "charge": "0.90",
  "start_count": "4250",
  "status": "In progress",
  "remains": "200",
  "currency": "USD"
}

Possible status values: Pending, In progress, Processing, Completed, Partial, Canceled.

5. Multiple order status

Check many orders in one call. Pass a comma-separated list of IDs in the orders parameter. The response is keyed by order ID, so an agent polls a whole campaign in a single round trip instead of one call per order.

Request

key=YOUR_API_KEY
action=status
orders=23501,23502,23503

Response

{
  "23501": {
    "charge": "0.90",
    "start_count": "4250",
    "status": "Completed",
    "remains": "0",
    "currency": "USD"
  },
  "23502": {
    "charge": "9.00",
    "start_count": "1200",
    "status": "In progress",
    "remains": "500",
    "currency": "USD"
  },
  "23503": {
    "error": "Incorrect order ID"
  }
}

6. Refill

Requests a refill on an order whose service supports it (refill: true in the service list) and returns a refill ID to track. Pass a single order or a comma-separated orders list. So an agent can request refills in bulk after a status check flags drops.

Request (single)

key=YOUR_API_KEY
action=refill
order=23501

Response

{
  "refill": 4001
}

Request (multiple)

key=YOUR_API_KEY
action=refill
orders=23501,23502

Response

[
  { "order": 23501, "refill": 4001 },
  { "order": 23502, "refill": { "error": "Refill not available" } }
]

7. Cancel

Requests cancellation of orders not yet processed (services with cancel: true). Pass a comma-separated orders list; the response reports the outcome per order. The undo an agent reaches for when something is queued by mistake.

Request

key=YOUR_API_KEY
action=cancel
orders=23501,23502

Response

[
  { "order": 23501, "cancel": 1 },
  { "order": 23502, "cancel": { "error": "Incorrect order ID" } }
]

8. Balance

Returns your account balance and currency. An agent reads it to gate spend before placing an order, and your own panel reads it to show funds. The cheapest call to confirm there is money to spend.

Request

key=YOUR_API_KEY
action=balance

Response

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

Call it from anything

One endpoint, plain form parameters. So a shell, a cron job, or an agent can drive it the same way. Here is a complete order placed from the command line:

curl -X POST https://api.socialgo.com/api/v2 \
  -d "key=YOUR_API_KEY" \
  -d "action=add" \
  -d "service=1" \
  -d "link=https://instagram.com/example" \
  -d "quantity=1000"

Notes & best practices

• Read before you write. Call services (or balance) to confirm the rate, limits, and funds, then call add. The same search-then-act guardrail the dashboard and MCP server use so nothing spends without a confirmed price.
• Cache the service list and refresh it periodically, IDs, rates, and limits change.
• Validate min/max quantities before submitting an order to avoid rejected calls.
• Poll status in batches with the multiple-orders call instead of one request per order.
• Keep your key server-side. If it is ever exposed, rotate it immediately from the dashboard.