Общий доступ к папкам и проектам через API

API открывает общий доступ к папке или проекту по публичной ссылке. В Kinescope этот механизм называется шерингом (sharing), а в API используются пути и поля shares, share_id и reset-token. Получателю не нужен аккаунт Kinescope: он видит видео и подпапки в браузере, а при необходимости вводит пароль.

Эндпоинты /v1/shares помогают создать ссылку из LMS, CRM или собственного бэкенда, настроить её и закрыть доступ. Перед началом работы прочитайте общие правила API.

Когда настраивать общий доступ из кода

• LMS выдаёт доступ после оплаты. Бэкенд создаёт ссылку на папку с уроками и отправляет её студенту.
• Нужен временный доступ. Укажите дату окончания для подрядчика или партнёра.
• Ссылка попала не тому получателю. Сбросьте её и передайте новый адрес, не меняя остальные настройки.
• Подписка закончилась. Отзовите доступ ко всем материалам одной командой.

Если хотя бы один сценарий вам знаком — читайте дальше.

Как работает общий доступ

1. Вы создаёте общий доступ к папке или проекту и получаете share_id, token и готовую ссылку.
2. Получатель открывает ссылку https://kinescope.io/sh/{token} и видит каталог без входа в Kinescope.
3. Для одной папки или проекта существует только одна активная ссылка.
4. Через PATCH можно изменить пароль, срок доступа, разрешение на скачивание или название.
5. reset-token выдаёт новый адрес, а DELETE окончательно отзывает доступ.

Папка и проект используют один механизм: в запросе достаточно передать ID нужного объекта в entity_id.

Что подготовить

• API-токен рабочей зоны в заголовке Authorization: Bearer YOUR_API_TOKEN.
• Платный тариф: создание ссылки на бесплатном тарифе недоступно.
• ID папки или проекта. Получить их можно при загрузке файлов через API.
• Роль admin, editor+, editor или manager. Роль viewer может читать настройки существующей ссылки, но не изменять их.

Создайте публичную ссылку

POST https://api.kinescope.io/v1/shares

curl -X POST 'https://api.kinescope.io/v1/shares' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Курс по Python — поток 12",
    "password": "python-2026",
    "allow_download": true,
    "expires_at": "2026-12-01T00:00:00Z"
  }'

Поля запроса:

Если заданы обе даты, starts_at должен быть раньше expires_at. Пароль короче четырёх символов не пройдёт проверку API.

Успешный запрос возвращает 201 Created:

{
  "data": {
    "share_id": "9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41",
    "entity_id": "5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77",
    "display_name": "Курс по Python — поток 12",
    "has_password": true,
    "allow_download": true,
    "starts_at": null,
    "expires_at": "2026-12-01T00:00:00Z",
    "is_active": true,
    "token": "iVv6uEZ5V3DZ2ytZ28RUru",
    "link": "https://kinescope.io/sh/iVv6uEZ5V3DZ2ytZ28RUru"
  }
}

Сохраните share_id: он понадобится для последующих запросов. Отправьте получателю значение link.

Получите настройки существующей ссылки

Если известен share_id, запросите настройки напрямую:

curl 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Если известен только ID папки или проекта, используйте entity_id:

curl 'https://api.kinescope.io/v1/shares/entity/5b8a54a1-1f4f-4a5f-9a3a-2a4b0e2f1c77' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Оба запроса возвращают активную ссылку. После отзыва она не находится ни по share_id, ни по entity_id.

Измените пароль, сроки и скачивание

PATCH https://api.kinescope.io/v1/shares/{share_id}

Передавайте только поля, которые нужно изменить:

curl -X PATCH 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "password": "new-password",
    "allow_download": false,
    "expires_at": "2027-01-15T00:00:00Z"
  }'

Смена или удаление пароля завершает активные сессии получателей. Им потребуется открыть ссылку и пройти проверку доступа заново.

Смените адрес ссылки

Если ссылку нужно заменить, вызовите reset-token:

curl -X POST 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41/reset-token' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

В ответе придёт новый объект общего доступа с новыми share_id, token и link. Все настройки сохранятся, а старый адрес перестанет работать сразу. Обновите сохранённый share_id и отправьте получателям новую ссылку.

Отзовите доступ

DELETE https://api.kinescope.io/v1/shares/{share_id}

curl -X DELETE 'https://api.kinescope.io/v1/shares/9f1d3c02-77a0-4f5e-8b26-1e0a5d3c8b41' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

После отзыва ссылка и все глубокие ссылки на видео или подпапки перестают работать. Чтобы снова открыть доступ, создайте новую ссылку.

Обработайте типовые ошибки

При повторном POST для одной папки или проекта API возвращает 409. Сначала получите существующую ссылку по entity_id, затем обновите или отзовите её.

Что дальше?

1. Загрузка файлов через API — получите ID проекта или папки и наполните её видео.
2. Общие правила API — авторизация, формат ошибок и лимиты запросов.
3. Как поделиться папкой или проектом — кабинетный сценарий и поведение для получателя.

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