API
Use the API to access Zemiax services from your panel account.
Quick start
Send URL-encoded form fields with HTTP POST. Responses are JSON.
Your client key
Sign in to reveal your client key and run authenticated requests from the same panel account.
First request: services
curl --silent --show-error --request POST 'https://zemiax.com/api/v2' \ --data-urlencode 'key=YOUR_API_KEY' \ --data-urlencode 'action=services'
Complete code examples
API_URL='https://zemiax.com/api/v2'
: "${ZEMIAX_API_KEY:?Set ZEMIAX_API_KEY in the server environment}"
body_file="$(mktemp)"
headers_file="$(mktemp)"
trap 'rm -f "$body_file" "$headers_file"' EXIT
http_status=$(curl --silent --show-error --request POST "$API_URL" \
--connect-timeout 5 --max-time 20 \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode "key=$ZEMIAX_API_KEY" \
--data-urlencode 'action=services' \
--dump-header "$headers_file" --output "$body_file" --write-out '%{http_code}')
curl_exit=$?
if [ "$curl_exit" -ne 0 ]; then
printf 'Transport error (curl exit %s).\n' "$curl_exit" >&2
exit "$curl_exit"
fi
if ! jq empty "$body_file"; then
printf 'The response was not valid JSON.\n' >&2
exit 1
fi
if [ "$http_status" -lt 200 ] || [ "$http_status" -ge 300 ]; then
printf 'HTTP %s: ' "$http_status" >&2
jq -c '{error, status}' "$body_file" >&2
if [ "$http_status" = '429' ]; then grep -i '^Retry-After:' "$headers_file" >&2 || true; fi
exit 1
fi
if jq -e 'type == "object" and has("error")' "$body_file" >/dev/null; then
jq -c '{error, status}' "$body_file" >&2
exit 1
fi
jq . "$body_file"
<?php
$apiUrl = 'https://zemiax.com/api/v2';
$apiKey = getenv('ZEMIAX_API_KEY');
if ($apiKey === false || $apiKey === '') {
throw new RuntimeException('Set ZEMIAX_API_KEY in the server environment.');
}
$body = http_build_query([
'key' => $apiKey,
'action' => 'services',
], '', '&', PHP_QUERY_RFC3986);
$handle = curl_init($apiUrl);
curl_setopt_array($handle, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 20,
]);
$response = curl_exec($handle);
if ($response === false) {
$transportError = curl_error($handle);
curl_close($handle);
throw new RuntimeException('Transport error: ' . $transportError);
}
$httpStatus = (int) curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
curl_close($handle);
try {
$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $error) {
throw new RuntimeException('The API response was not valid JSON.', 0, $error);
}
if ($httpStatus < 200 || $httpStatus >= 300) {
throw new RuntimeException('HTTP ' . $httpStatus . ': ' . (string) ($data['error'] ?? 'request failed'));
}
if (is_array($data) && isset($data['error'])) {
throw new RuntimeException('API error ' . (string) ($data['status'] ?? '') . ': ' . (string) $data['error']);
}
echo json_encode($data, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES), PHP_EOL;
import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen
API_URL = 'https://zemiax.com/api/v2'
API_KEY = os.environ.get('ZEMIAX_API_KEY')
if not API_KEY:
raise RuntimeError('Set ZEMIAX_API_KEY in the server environment.')
body = urlencode({'key': API_KEY, 'action': 'services'}).encode('utf-8')
request = Request(
API_URL,
data=body,
headers={'Content-Type': 'application/x-www-form-urlencoded'},
method='POST',
)
try:
with urlopen(request, timeout=20) as response:
http_status = response.status
raw_body = response.read()
except HTTPError as error:
http_status = error.code
raw_body = error.read()
retry_after = error.headers.get('Retry-After')
except URLError as error:
raise RuntimeError(f'Transport error: {error.reason}') from error
try:
data = json.loads(raw_body)
except json.JSONDecodeError as error:
raise RuntimeError(f'HTTP {http_status}; response was not valid JSON.') from error
if not 200 <= http_status < 300:
raise RuntimeError(f'HTTP {http_status}: {data.get("error", "request failed")}')
if isinstance(data, dict) and 'error' in data:
raise RuntimeError(f'API error {data.get("status", "")}: {data["error"]}')
print(json.dumps(data, indent=2, ensure_ascii=False))
const API_URL = 'https://zemiax.com/api/v2';
const apiKey = process.env.ZEMIAX_API_KEY;
if (!apiKey) throw new Error('Set ZEMIAX_API_KEY in the server environment.');
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 20_000);
(async () => {
try {
const response = await fetch(API_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({ key: apiKey, action: 'services' }),
signal: controller.signal,
});
const rawBody = await response.text();
let data;
try {
data = JSON.parse(rawBody);
} catch {
throw new Error(`HTTP ${response.status}; response was not valid JSON.`);
}
if (!response.ok) {
const retryAfter = response.headers.get('Retry-After');
throw new Error(`HTTP ${response.status}: ${data.error || 'request failed'}${retryAfter ? `; retry after ${retryAfter}s` : ''}`);
}
if (data && typeof data === 'object' && Object.prototype.hasOwnProperty.call(data, 'error')) {
throw new Error(`API error ${data.status || ''}: ${data.error}`);
}
console.log(JSON.stringify(data, null, 2));
} catch (error) {
if (error.name === 'AbortError') throw new Error('Request timed out; check the result before retrying a write.');
throw error;
} finally {
clearTimeout(timeout);
}
})().catch((error) => {
console.error(error.message);
process.exitCode = 1;
});
Documentation index
Service list
action=services
| Parameters | Description |
|---|---|
| key | Your API key |
| action | services |
[
{
"service": "<integer_service_id>",
"name": "<service_name>",
"desc": "<service_description>",
"type": "<service_type>",
"category": "<category_name>",
"rate": "<current_rate>",
"min": "<minimum_quantity>",
"max": "<maximum_quantity>",
"refill": "<boolean>",
"cancel": "<boolean>",
"dripfeed": "<boolean>"
}
]
The service ID is an integer; refill, cancel and dripfeed are booleans. The values in the response block are placeholders, not service data.
Add order
action=add
| Parameters | Description |
|---|---|
| key | Your API key |
| action | add |
| service | Service ID |
| link | Link to page |
| quantity | Needed quantity where required by the service behavior |
| comments (optional) | Custom comments; each non-empty line counts toward quantity |
| username (optional) | Username for service behaviors that require it |
| runs (optional) | Runs for compatible drip-feed services |
| interval (optional) | Interval in minutes for compatible drip-feed services |
{
"order": "<integer_order_id>"
}
The response may also include duplicate_guard: true for a matching recent request, or digital_license when digital fulfillment returns a non-empty payload. duplicate_guard is a detection signal, not an idempotency key or a guarantee that retrying is safe. digital_license fields depend on the fulfillment result.
Order status
action=status
Single order
| Parameters | Description |
|---|---|
| key | Your API key |
| action | status |
| order | Order ID |
{
"charge": "<charged_amount>",
"start_count": "<start_count>",
"status": "<order_status>",
"remains": "<remaining_quantity>",
"currency": "<account_currency>"
}
Multiple orders
| Parameters | Description |
|---|---|
| key | Your API key |
| action | status |
| orders | Order IDs separated by commas; maximum 100 unique IDs |
{
"<order_id>": {
"charge": "<charged_amount>",
"start_count": "<start_count>",
"status": "<order_status>",
"remains": "<remaining_quantity>",
"currency": "<account_currency>"
}
}
Subscription status
| Parameters | Description |
|---|---|
| key | Your API key |
| action | status |
| order | Order ID |
{
"status": "<subscription_status>",
"posts": "<posts>",
"old_posts": "<old_posts>"
}
Drip-feed status
| Parameters | Description |
|---|---|
| key | Your API key |
| action | status |
| order | Order ID |
{
"status": "<order_status>",
"runs": "<runs>"
}
For multiple orders, each order ID maps to that order type’s response fields. An order ID the account cannot access maps to an error object.
Create refill
action=refill
Single order
| Parameters | Description |
|---|---|
| key | Your API key |
| action | refill |
| order | Order ID |
{
"refill": "<refill_task_id>"
}
Multiple orders
| Parameters | Description |
|---|---|
| key | Your API key |
| action | refill |
| orders | Order IDs separated by commas; maximum 100 unique IDs |
{
"<order_id>": {
"refill": "<refill_task_id>"
}
}
A response may add already: true when a matching refill request already exists.
Get refill status
action=refill_status
Single refill
| Parameters | Description |
|---|---|
| key | Your API key |
| action | refill_status |
| refill | Refill ID |
{
"status": "<refill_status>"
}
Multiple refills
| Parameters | Description |
|---|---|
| key | Your API key |
| action | refill_status |
| refills | Refill IDs separated by commas; maximum 100 unique IDs |
{
"<refill_id>": {
"status": "<refill_status>"
}
}
Create cancel
action=cancel
Single order
| Parameters | Description |
|---|---|
| key | Your API key |
| action | cancel |
| order | Order ID |
{
"cancel": "<cancel_task_id>"
}
Multiple orders
| Parameters | Description |
|---|---|
| key | Your API key |
| action | cancel |
| orders | Order IDs separated by commas; maximum 100 unique IDs |
{
"<order_id>": {
"cancel": "<cancel_task_id>"
}
}
A response may add already: true when a matching cancel request already exists.
User balance
action=balance
| Parameters | Description |
|---|---|
| key | Your API key |
| action | balance |
{
"balance": "<current_balance>",
"currency": "<account_currency>"
}
Add order fields by service type
The services action returns each service type and its current min/max. Send only fields required by the selected service. These rows describe payload-preparation behaviors, not guaranteed catalog labels or availability; when present, the upstream raw type can be returned as the displayed type.
| Service behavior | Fields and rules |
|---|---|
| Standard quantity | Required: link, quantity. The current service min/max are enforced. |
| Fixed package | Required: link. Configured package quantity and charge are used; do not send quantity. |
| Custom comments | Required: link and non-empty comments. Send one comment per line; non-empty lines determine quantity. |
| Custom Comments Package | Required: link and non-empty comments, one comment per line. One package is charged at the listed rate; quantity is not used. |
| Mentions, User Followers, Comment Likes | Required: link and quantity. An empty or omitted username falls back to link. Current service min/max are enforced. |
| Mentions with Hashtags | Required: link, quantity, non-empty multiline usernames and hashtags. Current service min/max are enforced. |
| Mentions Custom List | Required: link and non-empty multiline usernames. Quantity is the number of non-empty usernames; current service min/max are enforced. |
| Mentions Hashtag | Required: link, quantity, and a non-empty hashtag or hashtags alias. Current service min/max are enforced. |
| Mentions Media Likers | Required: link, quantity, and non-empty media. Current service min/max are enforced. |
| Comment Replies | Required: link, username, and non-empty comments. Send one comment per line; non-empty lines determine quantity. |
| Poll | Required: link, quantity, answer_number. Current service min/max are enforced. |
| Invites from Groups | Required: link, quantity, and non-empty multiline groups. Current service min/max are enforced. |
| SEO | Required: link, quantity, and non-empty multiline keywords or the keyword alias. Current service min/max are enforced. |
| Subscriptions: range or provider | Required: username, min, max, and at least one positive posts or old_posts value. Range bounds are checked against service min/max; delay and expiry are optional where supported. |
| Subscriptions: configured limit | Required: username. If omitted, link supplies it. The configured service profile determines the post limit and expiry; request quantity/range fields are not used. |
| Drip-feed | Only default quantity and fixed package behaviors support it, when enabled for the service. Send positive runs and interval; both fields can enable it automatically. Total quantity is checked against service bounds. |
- The service listing type may contain the upstream raw type instead of one of the behavior names above. The runtime behavior is selected from service configuration and upstream type mapping.
- For subscription delay, input values up to 240 are interpreted as minutes and values above 240 as seconds. Omitted expiry defaults to 30 days for range/provider subscriptions.
Errors and rate limits
Read the HTTP response code and JSON body separately. Most API validation errors return HTTP 200 with an error and sometimes a logical status; that body status is not the HTTP code.
| HTTP | JSON body | Next step |
|---|---|---|
| 200 | Incorrect request | Send key and a supported action in a URL-encoded POST body; check required fields. |
| 200 | status 102, 103, 117 or 118 | Check the API key, account state, API IP allowlist, or account review state in the panel. |
| 200 | status 104 or 105 | Check that the order belongs to this account and that the service is visible and active. |
| 200 | status 107 | Compare the submitted fields with the selected service behavior and retry only after correcting the request. |
| 200 | status 108, 109, 111 or 112 | Check the service min/max and the requested quantity or subscription range. |
| 200 | status 110 | Set subscription min no higher than max. |
| 200 | status 113 or 115 | Check the account balance and the service inputs that determine the charge. |
| 200 | status 114 | The order could not be created; internal provider and database details are intentionally hidden. Reconcile order history before retrying. |
| 200 | status 116 | Drip-feed is not available for this request. Remove drip-feed fields or choose a service whose API listing reports it. |
| 429 | status "429"; Too many requests | Pause until Retry-After or X-RateLimit-Reset; do not keep sending requests while limited. |
| 503 | status "503" | The API security policy store is temporarily unavailable. Check again later; reconcile any write with an uncertain result first. |
| 5xx | Server / transport error | Inspect the HTTP response and JSON if present. A timeout does not prove that a write failed. |
Effective limits are read from the current runtime configuration. Each response can include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix time); Retry-After is sent when the bucket is limited.
- Per IP 1200 requests per 60s
- Per API key 600 requests per 60s
Security and efficient status polling
Keep the API key in server-side configuration or a secret manager. Send it only in the POST body; never put it in a URL, browser JavaScript, a public frontend, source control, or request logs. After signing in, reveal or manage your key on this API page.
Efficient status polling
Use status and refill_status only for items that still need checking, and request multiple IDs together when useful. The CSV parsers accept up to 100 unique IDs per request; order lists ignore invalid IDs, while refill lists ignore empty tokens. Space out polling and honor the rate-limit headers.
For ordinary orders, Pending, Processing, and In progress are active; Completed, Partial, Canceled, and Failed are terminal states recognized by the panel. The API returns the stored order status, so do not treat an unfamiliar provider status as final. Subscription orders return their subscription status; Active and Limit are not completed orders.
Refill status can be Pending, Completed, Rejected, or Error. Completed and Rejected are conclusive. Inspect error when status is Error; Request work limit reached is a per-request check budget, not a provider completion result.