ДОКУМЕНТАЦИЯ API

Публичный REST API. Аутентификация по ключу, документировано в OpenAPI.

Читай свой каталог OGRECORDS™ и управляй Smartlinks и черновиками релизов программно — через простой REST API. Аутентифицируйся с помощью scoped API-ключа из панели управления. Доступ на ранней стадии по запросу.

Справочник APIУправление API-ключамиЗапросить доступ на ранней стадии

Обзор: REST API, scoped-ключи, лимиты запросов, OpenAPI

Чтение + запись через REST

Читай релизы, треки, Smartlinks и статистику — и создавай или редактируй свои Smartlinks и черновики релизов — через простой HTTPS. Ответы в формате JSON, пагинация через limit/offset, предсказуемые схемы. Дистрибуция и отправка релизов не входят в API.

Scoped API-ключи

Аутентифицируйся с помощью ключа ogr_pk_ как Bearer-токен или в заголовке X-API-Key. Каждый ключ имеет явные права доступа — read:releases, read:smartlinks, read:stats, write:smartlinks, write:releases — и может быть в любой момент в панели управления пересоздан или отозван.

Лимиты запросов + заголовки

Каждый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. При превышении лимита возвращается статус 429 с Retry-After. Бесплатные ключи — 1000 запросов в день, ключи для бизнеса — 100 000.

Самостоятельно хостимая OpenAPI 3.0

Полная машинно-читаемая спецификация доступна по адресу /api/v1/public/openapi.json и отображается как интерактивная справка на этой странице — никаких сторонних хостов документации, никаких внешних вызовов.

ОБЗОР ЭНДПОИНТОВ

Эндпоинты для запуска.

Каждый эндпоинт аутентифицируется с помощью scoped API-ключа и доступен по адресу https://api.og-records.com. Эндпоинты для чтения и записи с ограниченными правами владельца для Smartlinks и черновиков релизов — дистрибуция и отправка релизов не экспортируются.

Релизы

  • GET/api/v1/public/releasesСписок твоих релизов. Пагинация через limit и offset.
  • GET/api/v1/public/releases/{id}Один релиз по ID.
  • POST/api/v1/public/releasesСоздать черновик релиза (write:releases). Требуется KYC и онбординг.
  • PATCH/api/v1/public/releases/{id}Обновить метаданные черновика (write:releases). Только для черновиков до отправки.
  • DELETE/api/v1/public/releases/{id}Удалить черновик релиза (write:releases).

Треки

  • GET/api/v1/public/tracks?release_id={id}Треки релиза, который тебе принадлежит.
  • GET/api/v1/public/tracks/{id}Один трек по id.

Smartlinks

  • GET/api/v1/public/smartlinksСписок твоих Smartlinks.
  • POST/api/v1/public/smartlinksСоздать Smartlink для своего релиза (write:smartlinks).
  • PATCH/api/v1/public/smartlinks/{id}Обновить свой Smartlink (write:smartlinks).
  • DELETE/api/v1/public/smartlinks/{id}Отключить Smartlink (write:smartlinks).

Статистика и спецификации

  • GET/api/v1/public/stats/release/{id}Стримы, слушатели и сохранения с разбивкой по DSP и странам. range = 7d, 14d, 30d, 90d, 1y или ytd.
  • GET/api/v1/public/openapi.jsonДокумент OpenAPI-3.0. Доступен публично и кэшируется — ключ не нужен.

Артисты и доходы

  • GET/api/v1/public/artistsСписок твоих артистов из роаста (read:artists).
  • GET/api/v1/public/earnings/balanceСнимок баланса твоего кошелька в USD (read:earnings).
ВЕБХУКИ

Получай уведомления, когда статус релиза изменится.

Зарегистрируй HTTPS-эндпоинт, и мы будем POSTить подписанное JSON-событие, как только один из твоих релизов будет доставлен, отклонён или снят. Эндпоинты ты управляешь в панели — каждый получает своё уникальное Signing-Secret, которое показывается один раз.

События при запуске

  • release.delivered — релиз был доставлен в магазины.
  • release.rejected — магазин или этап QC отклонил релиз.
  • release.takedown — релиз был снят.
  • release.live — релиз теперь доступен в магазинах.

Каждая доставка содержит эти заголовки

  • X-Webhook-Signature — lowercase-hex HMAC-SHA256 от тела запроса, с твоим Signing-Secret как ключом.
  • X-Webhook-Timestamp — время отправки в формате ISO-8601, совпадает с created_at в теле.
  • X-Webhook-Event — название события, например release.delivered.
  • X-Webhook-Id — уникальный идентификатор для этой доставки.

Полезная нагрузка — это JSON-тело с id, event, created_at и объектом data, содержащим release_id. Для проверки пересчитай HMAC-SHA256 от точного тела запроса с использованием своего Signing-Secret и сравни результат с X-Webhook-Signature с учётом времени (timing-safe), затем убедись, что X-Webhook-Timestamp находится в пределах примерно пяти минут, чтобы отклонить повторы.

Неудачные доставки повторяются с экспоненциальной задержкой. После 15 последовательных ошибок эндпоинт автоматически отключается, и ты должен зарегистрировать его заново, чтобы продолжить.

Управление вебхуками в твоём панели управления.

АУТЕНТИФИКАЦИЯ

API-ключи с правами доступа (scopes).

Создай ключ в своём панели управления и отправь его в заголовке Authorization: Bearer ogr_pk_… или в заголовке X-API-Key. Каждый ключ имеет ограниченные права — read:releases, read:smartlinks, read:stats, write:smartlinks, write:releases — чтобы интеграция получала только то, что нужно. Ключи можно в любой момент заменить или отозвать. Права на запись — scoped по владельцу и никогда не инициируют релиз; OAuth не входит в этот релиз.

ОГРАНИЧЕНИЯ ПО СКОРОСТИ

Что может делать твой ключ.

Бесплатно
1 000 запросов / день

Стандарт для каждого нового ключа. Подходит для панелей, синхронизации по cron и прототипирования.

Бизнес
100 000 запросов / день

Больший дневной лимит для продакшн-интеграций. По запросу.

Каждый ответ содержит X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset. Если лимит исчерпан, возвращается 429 с заголовком Retry-After — количество секунд до сброса окна.

ДОСТУП НА РАННЕЙ СТАДИИ

Строй на своём каталоге.

Публичный API находится в стадии Early Access. Напиши нам, что ты хочешь построить, и мы активируем API-ключи для твоего аккаунта.

Запросить доступ на ранней стадииПрочитать справку