Admin API: request, response and error format

The rules on this page apply to all Admin API methods. The address, token and access types are described on the Admin API: overview and authorization page, and the parameters of individual methods on the pages of their sections.

Request body

• The body is a single JSON object in UTF-8 encoding. An array at the top level or several objects in a row are not accepted.
• Body size — up to 1 MiB.
• Unknown fields are skipped without an error. Exceptions: POST /api/v1/spend/snapshots and the definition field of a saved report — there an extra field gives a 422 error.
• The Content-Type header is not checked for JSON requests. Files and archives are uploaded as multipart/form-data.

An empty body, a body larger than 1 MiB, invalid JSON and a value of the wrong type give code 400 in most methods:

{"code": "bad_request", "message": "invalid json"}

Some methods return a different message, or respond with code 422 and code = validation.

Example of a request with a body:

curl -X POST https://panel.example.com/api/v1/affiliate-networks \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Network"}'

Response — code 201 and the created record.

Identifiers

Record IDs are UUIDs, for example 3f2b8c1e-5a47-4d1b-9c0e-7a6d2f4b8e10. They come in the id field on creation and in lists, and are inserted into the address: /api/v1/campaigns/{id}. A click is identified by its subid value.

An ID in the wrong format gives code 400:

{"code": "bad_request", "message": "некорректный идентификатор или значение"}

The message means “invalid ID or value”. A record with a correctly formed but non-existent ID gives 404 with code = not_found.

Success codes and response shapes

The response is JSON with the Content-Type: application/json; charset=utf-8 header.

A record comes as an object without a wrapper. Lists come in one of these shapes:

An empty list is [], not null.

Non-JSON responses come from the report export (text/csv) and from downloading a page archive or the spend extension (application/zip).

Errors

The error body is the same for all methods:

{"code": "validation", "message": "name is required"}

• code — the code to handle in your integration.
• message — an explanation for a human, in Russian or English.

There are no other fields. Check the HTTP code and code together: some methods return validation with code 400.

Some methods have their own codes, for example export_quota or currency_rate. They are listed in the method descriptions. Codes 401, 402, 403 and 429 are covered on the Admin API: overview and authorization page.

Updating with PUT

PUT behaves differently depending on the resource.

Pagination

Page parameters depend on the method.

Do not set limit above the maximum. In campaign logs, reports/clicks, logs/audit, logs/{stream} and domain-replacements, a value above the maximum gives no error: it is replaced with the default value. In a report, such a value gives code 422; in logs/clicks and deliveries/search, code 400 with code = validation.

To go through a log with a cursor, pass cursor in the next request with the next_cursor value from the previous response. An empty next_cursor means there are no more records.

curl "https://panel.example.com/api/v1/logs/clicks?from=2026-10-01T00:00:00Z&to=2026-10-02T00:00:00Z&limit=200&cursor=<next_cursor>" \
  -H "Api-Key: <token>"

Other lists come in full. GET /api/v1/deliveries returns the last 200 records, GET /api/v1/report-exports up to 20, GET /api/v1/currency-rates up to 1000.

Sorting

Sorting can be set only in a report request — with the sort field:

{"sort": {"field": "profit", "direction": "desc"}}

• field — one of the selected groupings or a metric.
• direction — asc or desc.
• Without sort, the report is sorted by clicks in descending order.

The order of other lists cannot be configured:

• campaigns, offers, landing pages, sources, networks, domains, tokens — newest first;
• users, conversion types, custom metrics, blocklist registries — oldest first;
• streams — by position;
• domain groups — by name;
• saved reports — by modification date, newest first.

Dates and time zone

• Date and time — an RFC 3339 string: 2026-10-04T12:30:00Z or with an offset 2026-10-04T15:30:00+03:00. In a query string, encode the + sign as %2B.
• Calendar date — YYYY-MM-DD: the day field in spend and currency rates.
• The from and to period boundaries are exact moments in time. The time zone is taken from the string itself.
• Unix time: in seconds — server_time, expires_at and lease_until in GET /api/v1/license; in milliseconds — ts in GET /api/v1/logs/{stream}.

Without from and to, campaign logs, reports/clicks and logs/clicks return records for the last 24 hours. A date that could not be parsed is treated as not passed in campaign logs and reports/clicks, with no error. In logs/clicks and deliveries/search it gives code 400, in logs/audit — 422.

The report's time zone is set with the timezone field — a name from the IANA database, for example Europe/Moscow. An empty value means UTC. The time zone affects the calendar groupings hour, day, week, month, year, dow, hour_of_day. The week starts on Monday. More on the Period, time zone and attribution page.

The offer's daily cap, the stream's click caps and the stream schedule have their own time zone fields: cap_timezone, click_limits.timezone, schedule.tz. An empty value means UTC. In a spend snapshot, the timezone field is required: it is the ad account's time zone.

Money and currencies

• Amounts are JSON numbers, for example 12.5.
• The report currency is USD. The currency setting accepts only USD.
• A campaign's cost_value is set in USD, from 0 to 1,000,000,000. For the revshare model, it is a percentage from 0 to 100.
• A currency rate is set with the usd_rate field — how many USD one unit of the currency is worth.

A postback payout in another currency is converted to USD at the rate for the event date, and the rate is saved in the conversion. If there is no rate, the response is 422 with code = currency_rate. More on the Currencies and rates page.

Retrying requests

Code 503 with code = unavailable means a temporary failure:

{"code": "unavailable", "message": "temporary error, retry later"}

If the response has a Retry-After header, wait the number of seconds it specifies and repeat the same request. The usual value is 5. A report responds to a temporary failure with 503 and the report_unavailable code: repeat such a request later too.

A 503 response with the plain text Tracker maintenance in progress comes during maintenance — see the Base URL section.

The server allows 90 seconds for a response. For uploading files and page archives and for downloading a page archive, the limits are longer: 10 minutes to receive the request body and 15 minutes for the response. Get large reports with a background export: Admin API: reports.