Общие правила API

Эта страница описывает общие правила работы с Kinescope API, которые применяются ко всем эндпоинтам. Если вы только начинаете работать с API, начните отсюда.

Кому подходит эта статья

• Разработчикам — нужно начать работу с Kinescope API
• Backend-разработчикам — требуется понять базовые правила авторизации и форматы запросов
• DevOps-инженерам — нужно интегрировать Kinescope в автоматизированные процессы

Базовые сведения

Base URL

Все запросы к API выполняются по адресу:

https://api.kinescope.io

Версии API

Kinescope API использует версионирование через префиксы в URL:

Авторизация

Формат токена

Для авторизации в публичном API используется заголовок Authorization с типом Bearer:

Authorization: Bearer YOUR_API_TOKEN

Важно: API-токен должен быть в формате UUID (например, e51e55a1-7615-493e-9055-10ac9cc44ccd). Получить токен можно в Dashboard Kinescope в разделе Настройки → API-токены.

Workspace и токены

Каждый API-токен привязан к конкретной рабочей зоне (workspace). При выполнении запроса workspace определяется автоматически из токена — вам не нужно передавать его отдельно.

Все эндпоинты требуют заголовок Authorization: Bearer ....

Формат ответов

Успешный ответ

Все успешные ответы возвращаются в формате JSON с обёрткой:

{
  "data": {
    "id": "video-uuid",
    "title": "My Video",
    "status": "done"
  }
}

Ответ со списком и пагинацией

Списки возвращаются с метаданными о пагинации и сортировке:

{
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 156
    },
    "order": {
      "created_at": "desc"
    }
  },
  "data": [
    {"id": "video-1", "title": "First Video"},
    {"id": "video-2", "title": "Second Video"}
  ]
}

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

Все ответы API включают заголовок X-Request-ID с уникальным идентификатором запроса. Используйте его при обращении в поддержку:

X-Request-ID: 7127f2d7-0e96-40d0-9a03-2e987c096466

Пагинация

Для получения списков используйте параметры пагинации:

Пример:

curl "https://api.kinescope.io/v1/videos?page=2&per_page=25" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Сортировка

Используйте параметр order для сортировки результатов:

order=field.direction,field2.direction

• field — имя поля для сортировки
• direction — направление: asc (по возрастанию) или desc (по убыванию)
• Можно указать несколько полей через запятую

Примеры:

# Сначала новые, затем по алфавиту
curl "https://api.kinescope.io/v1/videos?order=created_at.desc,title.asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Только по дате создания (по возрастанию)
curl "https://api.kinescope.io/v1/videos?order=created_at.asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Если указать поле без направления, по умолчанию используется asc.

Важно: Не все поля доступны для сортировки. При указании недопустимого поля API вернёт ошибку с кодом 400216 (NOT_ALLOWED_ORDER_FIELD).

Формат дат

Для аналитики и временных интервалов

Параметры from и to поддерживают два формата:

1. Краткий формат: YYYY-MM-DD (например, 2024-01-01)
2. Полный формат: RFC3339 YYYY-MM-DDTHH:MM:SSZ (например, 2024-01-01T00:00:00Z)

Пример:

curl "https://api.kinescope.io/v1/analytics/overview?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Оба параметра обязательны для эндпоинтов аналитики.

Обработка ошибок

Формат ошибки

Все ошибки возвращаются в едином формате:

{
  "error": {
    "code": 404404,
    "message": "video not found",
    "detail": "The requested video does not exist or has been deleted"
  }
}

HTTP-коды ответов

Ошибка валидации

При ошибках валидации в ответе также присутствует массив invalid_params:

{
  "error": {
    "code": 400400,
    "message": "validation error",
    "invalid_params": [
      {
        "name": "title",
        "reason": "required",
        "message": "Title is required"
      },
      {
        "name": "privacy_type",
        "reason": "oneof",
        "message": "Must be one of: anywhere, nowhere, custom"
      }
    ]
  }
}

Специальные форматы ответов

CSV-экспорт

Некоторые эндпоинты поддерживают экспорт данных в формате CSV через суффикс .csv в URL:

Пример:

# JSON (по умолчанию)
curl "https://api.kinescope.io/v1/billing/invoices/123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# CSV
curl "https://api.kinescope.io/v1/billing/invoices/123.csv" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Важно: CSV-формат поддерживается не для всех эндпоинтов. Проверяйте документацию конкретного эндпоинта или пробуйте добавить .csv к URL — если формат не поддерживается, вернётся JSON.

Лимиты и ограничения

При превышении лимитов API вернёт 429 Too Many Requests.

Что дальше?

Теперь, когда вы знаете общие правила API, можете перейти к конкретным разделам:

1. Загрузка файлов через API — загрузка видео и дополнительных материалов
2. Kinescope API — полная документация API
3. Аналитика — получение статистики просмотров через API
4. JWT-аутентификация для чата — настройка авторизации в чате трансляций
5. Авторизационный бэкенд — контроль доступа к видео

Остались вопросы? Напишите в чат поддержки — специалисты помогут!