Запросы и ответы
Формат запросов и ответов, идентификаторы, деньги и время.
Запрос
- Все запросы — по HTTPS на
https://api.skystream.su/app/v1. Запрос по HTTP отклоняется с ошибкой400 https_requiredи не перенаправляется. Ключ, отправленный по HTTP, мог быть перехвачен: отзовите его и выпустите новый. - Тело запроса — JSON с заголовком
Content-Type: application/json, не больше 64 КБ. Тело другого типа отклоняется с ошибкой415 unsupported_media_type. - Поля, которых у запроса нет, не игнорируются: запрос с лишним полем отклоняется с ошибкой
parameter_unknown. Опечатка в имени поля не проходит незаметно. - Изменяющие запросы (
PATCH) меняют только переданные поля. Чтобы очистить поле, где это допустимо, передайтеnull.
Ответ
- Тело ответа — JSON. Имена полей — в
snake_case. - Объект возвращается сам по себе, без обёртки.
- Список возвращается объектом
{"data": [...], "has_more": false}, даже если страниц нет. Подробнее — в разделе Пагинация. - Поле без значения передаётся как
null, а не опускается. Исключение — полеparamв ошибке: его нет, если ошибка не относится к одному полю. - Каждый ответ содержит заголовок
X-Request-Idс идентификатором запроса. Сообщайте его в поддержку, если запрос выполнился не так, как ожидалось. - Запросы ваших ключей видны в панели, раздел «API» → «Журнал запросов»: время, ключ, адрес, код ответа и ошибки, длительность, IP. У изменяющих запросов и у ошибок там же сохраняются тела запроса и ответа. Срок хранения указан в самом журнале.
- Ответы не кэшируются (
Cache-Control: no-store).
Коды ответа
| Код | Когда |
|---|---|
200 | Запрос выполнен |
201 | Объект создан: канал или заказ |
400, 402, 404, 413, 415, 422 | Ошибка в запросе. Повтор без изменений не поможет |
409 | Объект не в том состоянии: например, запуск уже идёт. Для idempotency_key_in_progress — дождитесь ответа на первый запрос и повторите |
401, 403 | Ключ не действует или у него нет права |
429 | Превышен предел частоты. Повторите запрос через время из Retry-After |
500, 502, 503 | Сбой на нашей стороне или в подключённом сервисе. Запрос можно повторить позже |
504 | API не успел ответить, и запрос мог выполниться. Повторите его с тем же Idempotency-Key или проверьте результат чтением |
Причина каждой ошибки — в поле error.code; перечень — в разделе Ошибки.
Идентификаторы
Идентификатор объекта — строка с префиксом его вида:
| Префикс | Объект |
|---|---|
ch_ | Канал |
run_ | Запуск |
gr_ | График онлайна |
vo_, fo_ | Заказ просмотров, заказ фолловеров |
cb_, cp_ | Заказ чат-ботов, заказ чат-панели |
tx_ | Операция по счёту |
key_ | Ключ API |
Храните идентификаторы строками и не разбирайте их. В адресе запроса идентификатор чужого объекта, несуществующего объекта и строка не того вида дают один и тот же ответ — 404 resource_missing: ответ не подтверждает, что объект с таким идентификатором существует. Идентификатор не того вида в параметре строки запроса (channel_id, starting_after) — ошибка в запросе: 400 parameter_invalid.
Деньги
Суммы передаются целым числом копеек вместе с валютой:
{ "amount": 15000, "currency": "RUB" }Это 150 рублей. Дробные рубли в JSON округлялись бы у клиента иначе, чем у нас, и сумма на экране расходилась бы со списанной.
Ставки за единицу услуги бывают дробными в копейках. Они передаются десятичной строкой в поле unit_amount_decimal: "3.5" — три с половиной копейки за единицу. Итог заказа округляется до целой копейки.
Время
Время передаётся строкой ISO 8601 в UTC: 2026-09-29T12:00:00.000Z. Сутки, по которым считается суточный потолок трат ключа, — московские.