REST API ГороскопчикCAST

Версия 1.2 База https://api.goroskopchikcast.io

Программный доступ к расписанию эфиров, ключам приёма RTMP, статусу трансляции, записям и подписчикам сообщества. Все запросы по HTTPS, ответы в формате JSON с кодировкой UTF-8.

Обзор

Корневой префикс ресурсов — /v1. Дата и время передаются в ISO 8601 в часовом поясе UTC, если явно не указано иное полем timezone.

Идентификаторы сущностей — строки ulid (26 символов). Пагинация курсорная: параметры запроса limit (по умолчанию 20, максимум 100) и cursor из предыдущего ответа.

Заголовки ответа

Заголовок	Описание
`X-Request-Id`	Идентификатор запроса для обращения в поддержку.
`X-RateLimit-Limit`	Лимит запросов в минуту для текущего ключа.
`X-RateLimit-Remaining`	Оставшаяся квота в текущем окне.

Авторизация

Для вызовов от имени стримера используется пара ключ доступа (публичный идентификатор) и секрет. Секрет передаётся только при обмене на токен и не дублируется в URL.

POST/v1/oauth/token

Тело запроса: grant_type=client_credentials, client_id, client_secret.

{
  "access_token": "gkst_live_************************",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "broadcast:write broadcast:read community:read vod:read"
}

Во всех последующих запросах передавайте заголовок Authorization: Bearer <access_token>.

GET /v1/me

Профиль текущего аккаунта: id, display_name, slug, флаги community_verified, obs_hint_enabled.

Эфиры

GET/v1/broadcasts

Список эфиров. Фильтры: status (scheduled, live, ended), from, to.

POST/v1/broadcasts

Создание эфира. Тело:

{
  "title": "Транзиты недели + разбор карт зрителей",
  "description": "Суббота, 19:00 МСК",
  "scheduled_at": "2026-04-19T16:00:00Z",
  "visibility": "community",
  "tags": ["transits", "natal", "live-reading"]
}

GET/v1/broadcasts/{broadcast_id}

Карточка эфира: расписание, статус, счётчики зрителей, связанный vod_id после завершения.

PATCH/v1/broadcasts/{broadcast_id}

Обновление метаданных до старта эфира.

POST/v1/broadcasts/{broadcast_id}/go-live

Перевод в состояние «в эфире» после успешного handshake с ingest. Возвращает 403, если не активирована учётная запись сообщества или ingest не получает поток.

POST/v1/broadcasts/{broadcast_id}/end

Завершение эфира и постановка записи в очередь обработки VOD.

RTMP и ключи приёма

GET/v1/broadcasts/{broadcast_id}/ingest

Возвращает параметры для OBS или другого энкодера:

{
  "rtmp_url": "rtmps://ingest.eu1.goroskopchikcast.io/live",
  "stream_key": "************************",
  "recommended_bitrate_kbps": { "min": 2500, "max": 8000 },
  "audio_codec": "aac",
  "video_codec": "h264"
}

Ключ приёма одноразово отображается полностью при первом запросе после создания эфира; далее маскируется. Для ротации ключа вызовите POST /v1/broadcasts/{broadcast_id}/ingest/rotate.

Записи и VOD

GET/v1/vod

Список готовых записей с пагинацией.

GET/v1/vod/{vod_id}

Метаданные: длительность, разрешение, статус обработки (processing, ready, failed).

GET/v1/vod/{vod_id}/playback

Подписанные URL для HLS и прогрессивной загрузки; срок действия ссылок — поле expires_at.

Сообщество

GET/v1/community/subscribers

Подписчики с фильтром tier и датой подписки.

POST/v1/community/announcements

Публикация анонса следующего эфира в ленту сообщества (текст, ссылка на эфир, запланированное время показа).

GET/v1/horoscope/feed

Выгрузка опубликованных выпусков «гороскопов онлайн» для встраивания на сайт или в приложение (только для верифицированных аккаунтов).

Вебхуки

Настройка конечной точки: POST /v1/webhooks/endpoints с полями url, events[]. Подпись HMAC-SHA256 передаётся в заголовке X-GoroskopchikCast-Signature.

Событие	Когда приходит
`broadcast.scheduled`	Эфир создан или перенесён.
`broadcast.started`	Ingest принял поток, эфир в статусе live.
`broadcast.ended`	Эфир завершён.
`vod.ready`	Запись обработана и доступна зрителям.
`subscriber.new`	Новый подписчик сообщества.

Ошибки и лимиты

Тело ошибки:

{
  "error": {
    "code": "ingest_not_connected",
    "message": "Источник сигнала не подключён к ingest.",
    "request_id": "01jqz..."
  }
}

HTTP	Код	Смысл
401	`unauthorized`	Неверный или просроченный токен.
403	`community_inactive`	Учётная запись сообщества не активирована.
403	`forbidden_scope`	Недостаточно прав у ключа.
404	`not_found`	Ресурс не существует или недоступен.
409	`broadcast_conflict`	Конфликт состояния (например, повторный go-live).
429	`rate_limited`	Превышена квота; повторите запрос позже.

Лимит по умолчанию — 120 запросов в минуту на ключ; burst до 30 запросов за 5 секунд. Для массовых операций используйте вебхуки и очереди на своей стороне.