Admin API: streams

14 methods for working with campaign streams. All of them require a token with Full access («Полный доступ») (full). Authorization is described on the Admin API: overview and authorization page, and the general request and error format on the Request, response and error format page.

Stream object

This object is returned and accepted by the create and edit methods, and returned by the list and copy methods.

For a stream without offers or landing pages, the offers and landers fields are null. If the share is not passed, it equals 100; an explicit 0 excludes the item from rotation. More about shares on the Rotation and split tests page, and about schedules and caps on the Stream schedule and click caps page.

Action and its parameters

action_payload can also contain a target_rotation object — the selection mode, the memory period and the order of items, see Setup through the API and in a JSON file. The tracker applies it in the offers, landing and funnel actions, and validates it with any action. The panel writes this object to a stream with any action.

What each action and redirect method does is described on the Stream actions and redirect methods page.

Filters

Each element of the filters array is one condition:

Conditions with the same group number are combined with OR, and groups with each other with AND. If no condition has group set, the conditions are combined according to the mode field. The value format of each field is described on the Stream filters page.

Campaign streams

List streams

GET /api/v1/campaigns/{id}/streams

Returns an array of the campaign's streams in ascending order of position. {id} is the campaign ID. Error: 404 — the campaign was not found.

Create a stream

POST /api/v1/campaigns/{id}/streams

Creates a stream in the {id} campaign. The body is a stream object.

curl -X POST https://panel.example.com/api/v1/campaigns/3f2a1c9e-5b7d-4e8a-9c1f-0a2b3c4d5e6f/streams \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "US mobile",
    "type": "regular",
    "action_type": "offers",
    "weight": 100,
    "position": 1,
    "filters": [
      {"type": "geo", "op": "in", "values": ["US"], "group": 1},
      {"type": "device", "op": "in", "values": ["mobile"], "group": 2}
    ],
    "offers": [{"id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f", "share": 100}],
    "click_limits": {"daily": 5000, "timezone": "Europe/Warsaw"}
  }'

Response — code 201 and the stream object with the new id. It contains the values you passed: the default values are visible in the stream list.

Errors:

• 400 bad_request — the body could not be parsed as a JSON object;
• 404 not_found — the campaign was not found;
• 422 validation — action_type is required; Укажите адрес для действия «Прямой URL» (specify the address for the Direct URL action); неизвестный тип или оператор фильтра: <type> (unknown filter type or operator); некорректное регулярное выражение в фильтре: <type> (invalid regular expression in the filter); код ответа действия «ничего»: 200 или 204 (the response code of the Nothing action: 200 or 204); Лимиты кликов: целые числа от 0 до 1 000 000 000 000 (click caps: integers from 0 to 1,000,000,000,000); Неизвестный часовой пояс лимита (unknown cap time zone); оффер недоступен: <id> (offer unavailable); лендинг недоступен: <id> (landing page unavailable).

Edit a stream

PUT /api/v1/streams/{id}

Changes the {id} stream. Pass only the fields you want to change: the rest are kept. A passed field is replaced entirely. To change one key in action_payload or one offer in offers, get the stream from the list, change the object and send it in full. For a stream with the redirect action, the new action_payload must contain a non-empty url, otherwise the request returns 422 with the text Укажите адрес для действия «Прямой URL». null in schedule or click_limits removes the schedule or the caps.

curl -X PUT https://panel.example.com/api/v1/streams/b7e6d5c4-3a2f-4b1e-9d0c-8f7e6d5c4b3a \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"state": "paused"}'

Response — code 200 and the stream object with all fields. The 400 and 422 errors are the same as when creating, except action_type is required; 404 — the stream was not found. You cannot move a stream to another campaign with this method.

Delete a stream

DELETE /api/v1/streams/{id}

Deletes the stream. Response — code 204 with no body. Error: 404 — the stream was not found.

Set the order of streams

POST /api/v1/campaigns/{id}/streams/reorder

Arranges the campaign's streams according to the list.

The first stream in the list gets position 0, the second one 1, and so on. Streams that are not in the list keep their previous position. IDs of streams from other campaigns are skipped. Response — code 204 with no body. Errors: 400 — the body could not be parsed or the list contains a value that is not a UUID; 404 — the campaign was not found.

Copy a stream

POST /api/v1/streams/{id}/clone

Creates a copy of the stream in the same campaign. No body is needed. The copy gets the name with the “ · copy” (« · копия») suffix, the paused state and a position after the last stream; offers, landing pages, filters, schedule and caps are carried over. Response — code 201 and the new stream object. Errors: 404 — the stream was not found; 422 — a condition, offer or landing page of the original stream did not pass validation.

Templates and import

How templates and files look in the panel is described on the Stream templates, export and import page.

Export a stream to a file

GET /api/v1/streams/{id}/export

Returns a portable description of the stream. Response — code 200, a Content-Disposition header with the file name stream-<id>.json, and the body:

{
  "format": "tracker-stream",
  "version": 1,
  "stream": {"id": "", "campaign_id": "", "name": "US mobile", "type": "regular", "action_type": "offers", "state": "paused", "position": 0}
}

stream contains all fields of the stream object; the example shows some of them. The stream and campaign IDs are empty, the state is paused, the position is 0. Only the keys from the actions table remain in action_payload. Error: 404 — the stream was not found.

Check a file before import

POST /api/v1/campaigns/{id}/stream-import/preview

Checks a template file for the {id} campaign and returns a ready draft. The stream is not created.

Response — code 200 and a stream object in the paused state with a position after the campaign's last stream. To create the stream, send this object with the “Create a stream” method.

Errors: 400 — Не удалось прочитать файл шаблона (could not read the template file); 404 — the campaign was not found; 422 — the file did not pass validation, and message contains the reason, for example Нужен шаблон tracker-stream версии 1 (a tracker-stream template of version 1 is required) or Шаблон больше 256 КиБ (the template is larger than 256 KiB). All the file limits are in the File limits section.

Save a stream as a template

POST /api/v1/streams/{id}/templates

Saves the settings of the {id} stream to the personal template library of the user who created the token.

Response — code 201 and the template object: id, name, definition — the same description that the export to a file returns, created_at. Errors: 400 — Некорректный запрос (invalid request); 404 — the stream was not found; 422 — Название шаблона: от 1 до 120 символов (template name: from 1 to 120 characters) or the stream did not pass the template validation.

List templates

GET /api/v1/stream-templates

Returns an array of the token creator's templates, newest first. Element fields: id, name, definition, created_at. Templates of other users are not included in the list.

Delete a template

DELETE /api/v1/stream-templates/{id}

Deletes a template from the token creator's library. Response — code 204 with no body. Error: 404 — the template was not found. Streams created from the template do not change.

Routing preview

POST /api/v1/campaigns/{id}/routing-preview

Shows which stream of the campaign a visitor with the given parameters will get. No click is recorded, and the cap counters do not change. All fields are optional; the letter case of field names is ignored.

curl -X POST https://panel.example.com/api/v1/campaigns/3f2a1c9e-5b7d-4e8a-9c1f-0a2b3c4d5e6f/routing-preview \
  -H "Api-Key: <token>" \
  -H "Content-Type: application/json" \
  -d '{"Country": "US", "Device": "mobile", "OS": "Android", "Browser": "Chrome", "SubIDs": {"sub_id_1": "fb"}}'

Response — code 200:

• streams — the campaign's streams. Each one has id, name, type, weight, position; eligible — whether the stream matches the visitor; filters — the result of each condition in the order of the stream's filters array; selected — true for the selected stream; reason — an explanation as text.
• campaign_state and rotation — the state and rotation mode of the campaign.
• at — the moment the calculation was made for.

The reason values and how to read the result are described on the Stream selection check page. Errors: 400 — the body could not be parsed; 404 — the campaign was not found; 422 — invalid IP.

Counters and statistics

Stream click cap counters

GET /api/v1/streams/{id}/click-limits

Returns how many entries are counted toward the stream's caps: hourly — for the current hour, daily — for the current day, total — in total. The hour and day are counted in the time zone of the stream's caps; if no caps are set — in UTC. Errors: 404 — the stream was not found; 503 with code unavailable — Счётчики временно недоступны (the counters are temporarily unavailable), repeat the request later.

Clicks by campaign stream

GET /api/v1/campaigns/{id}/stream-stats

Returns the clicks and unique clicks by the campaign's streams for the period.

Response — code 200 and an object with an items array. An element has three fields: stream_id, clicks, uniques. Streams without clicks for the period are not in the array. A value that is not in RFC 3339 format is replaced with the default value. Errors: 404 — the campaign was not found; 400 with code report_error — the statistics query failed.

Build other metrics by stream with the reports method grouped by stream — see Admin API: reports.

Errors

Offer unavailable («оффер недоступен») or landing page unavailable («лендинг недоступен»)

There is no offer or landing page with this id in the team. Only new items are checked: the ones that were already in the stream are not rechecked when it is edited.

Changes do not show up in traffic

Changes made through the API take effect immediately. Make sure the stream is in the active state: a copy and a stream from an import are created in the paused state.