API documentation

Overview

The base URL for every endpoint below is https://your-domain.com/api/v1.

All requests and responses use UTF-8 JSON. Successful responses are wrapped in a top-level data object; failures return an error object or standard validation errors.

{
  "data": { "...": "resource fields" }
}

success envelope

Authentication

Create keys in your dashboard under API keys. A key is issued as {key_prefix}.{secret} and the secret is shown exactly once.

Send it on every request as a Bearer token in the Authorization header:

curl https://your-domain.com/api/v1/balance \
  -H "Authorization: Bearer BP7XK2Q9M4TZ.aXc3_dQfGhR5kLmNp8vWyB2eJtUzHsDq4Ko9rTxN"

bash

Keys are scoped to your account: every order, balance and rate limit is tied to the user who owns the key. Revoked keys stop working immediately.

Endpoints

Six authenticated endpoints plus an unauthenticated health check.

GET /api/v1/ping

Health check. No authentication required.

Example response

{
  "pong": true,
  "version": "v1"
}

200 OK

GET /api/v1/services

List catalog services. When authenticated, your_price_per_unit reflects your tier pricing (retail, reseller or VIP).

Query parameters

Name	Type	Required	Description
platform	string	No	Filter by platform, e.g. instagram.
category	string	No	Category slug filter.
status	string	No	active (default), inactive or out_of_stock.
per_page	integer	No	Results per page, 1–100. Default 25.
page	integer	No	Page number.

Example request

curl "https://your-domain.com/api/v1/services?platform=instagram&per_page=50" \
  -H "Authorization: Bearer $API_KEY"

bash

Example response

{
  "data": [
    {
      "id": 42,
      "name": "Instagram Followers — Real",
      "slug": "ig-followers-real",
      "platform": "instagram",
      "category": "Social media",
      "category_slug": "social-media",
      "min": 100,
      "max": 100000,
      "price_per_unit": 0.9,
      "your_price_per_unit": 0.765,
      "speed": "fast",
      "avg_delivery_minutes": 45,
      "refill_supported": true,
      "status": "active"
    }
  ],
  "links": { "first": "...", "last": "...", "next": "...", "prev": null },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "per_page": 50,
    "to": 50,
    "total": 128
  }
}

200 OK

POST /api/v1/orders

Place an order. Funds are debited from your wallet atomically at server-computed prices. Identify the service by numeric id or by slug — exactly one is required.

Body parameters

Name	Type	Required	Description
service_id	integer	Yes*	Service id. Required if service (slug) is absent.
service	string	Yes*	Service slug. Required if service_id is absent.
link	string	Yes	Target profile URL or @username(alias: target).
quantity	integer	Yes	Amount to deliver. Must be within the service min/max.
coupon	string	No	Optional coupon code applied at quote time.
notes	string	No	Internal note stored with the order.

* Exactly one of service_id / service must be present.

Example request

curl -X POST https://your-domain.com/api/v1/orders \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "ig-followers-real",
    "link": "https://instagram.com/boostaplugg",
    "quantity": 1000,
    "coupon": "LAUNCH10"
  }'

bash

Example response

{
  "data": {
    "id": 9012,
    "order_number": "BP-20260822-004512",
    "status": "pending",
    "status_label": "Pending",
    "service_id": 42,
    "service_name": "Instagram Followers — Real",
    "quantity": 1000,
    "unit_price": 0.765,
    "charge_amount": 689.25,
    "discount_amount": 76.5,
    "currency": "USD",
    "target_link": "https://instagram.com/boostaplugg",
    "start_count": null,
    "remains": null,
    "mode": "demo",
    "coupon_code": "LAUNCH10",
    "item": {
      "service_id": 42,
      "quantity": 1000,
      "unit_price": 0.765,
      "amount": 689.25
    },
    "history": [
      {
        "from_status": null,
        "to_status": "pending",
        "note": null,
        "actor": "user:88",
        "at": "2026-08-22T09:30:12+00:00"
      }
    ],
    "placed_at": "2026-08-22T09:30:12+00:00",
    "completed_at": null,
    "created_at": "2026-08-22T09:30:12+00:00"
  }
}

201 Created

GET /api/v1/orders/{id}

Fetch one of your own orders including live delivery counters (start_count, remains) and a recent status history summary. Orders owned by other accounts return 404.

Path parameters

Name	Type	Required	Description
id	integer	Yes	Order id.

Example request

curl https://your-domain.com/api/v1/orders/9012 \
  -H "Authorization: Bearer $API_KEY"

bash

Returns the same order object shape as order creation.

GET /api/v1/orders

Paginated list of your orders, newest first.

Query parameters

Name	Type	Required	Description
status	string	No	pending, processing, in_progress, completed, partial, cancelled, refunded or failed.
per_page	integer	No	Results per page, 1–100. Default 25.
page	integer	No	Page number.

Example request

curl "https://your-domain.com/api/v1/orders?status=processing&page=2" \
  -H "Authorization: Bearer $API_KEY"

bash

POST /api/v1/cancel

Cancel one of your own orders. Only pending or processing orders can be cancelled; the charged amount is refunded to your wallet automatically.

Body parameters

Name	Type	Required	Description
order_id	integer	Yes	Id of the order to cancel.

Example request

curl -X POST https://your-domain.com/api/v1/cancel \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": 9012}'

bash

Example response

{
  "data": {
    "id": 9012,
    "status": "cancelled",
    "status_label": "Cancelled",
    "...": "full order object"
  }
}

200 OK

GET /api/v1/balance

Wallet summary for the key owner.

Example request

curl https://your-domain.com/api/v1/balance \
  -H "Authorization: Bearer $API_KEY"

bash

Example response

{
  "data": {
    "balance": 1240.55,
    "currency": "USD",
    "locked": false,
    "total_deposited": 5200,
    "total_spent": 3959.45,
    "open_orders": 3
  }
}

200 OK

Errors

Non-validation failures use a stable machine-readable code inside an error envelope:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Insufficient wallet balance. Required: 120.00, available: 98.40."
  }
}

error envelope

HTTP	Code	When
401	unauthenticated	Missing, malformed, invalid or revoked credentials.
402	insufficient_balance	Wallet lacks funds or is locked.
403	forbidden	Account suspended or action not permitted.
404	not_found	Resource does not exist or belongs to another account.
422	validation_error / invalid_request	Validation failures return Laravel-standard errors with field messages; business-rule violations return invalid_request.
429	rate_limited	Key exceeded its per-minute limit. Includes Retry-After header.

Validation error example

{
  "message": "The quantity field is required.",
  "errors": {
    "quantity": ["The quantity field is required."]
  }
}

422 Unprocessable Entity

Rate limits

Every key has its own per-minute limit, shown when you create it (default 120 requests/min). Responses include rate-limit headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
Retry-After: 23   (only present on 429 responses)

headers

On HTTP 429 wait for the number of seconds given by Retry-After before retrying. Requests are counted against the window as soon as they are accepted.

Pagination

List endpoints accept page and per_page (max 100). Responses carry Laravel-style links and meta objects alongside data:

{
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://your-domain.com/api/v1/orders",
    "per_page": 25,
    "to": 25,
    "total": 62
  }
}

Changelog

v1 · current
- Initial release: services listing, order creation, order lookup, order listing, cancellation, wallet balance.
- Tier-aware pricing, coupons, per-key throttling and request logging.

Automate your orders end to end

Overview

Authentication

Endpoints

Example response

Query parameters

Example request

Example response

Body parameters

Example request

Example response

Path parameters

Example request

Query parameters

Example request

Body parameters

Example request

Example response

Example request

Example response

Errors

Validation error example

Rate limits

Pagination

Changelog