HTTP API

Базовый адрес — https://kuralesia.ru/api/v1. Все запросы и ответы в UTF-8, тела — JSON, кроме передачи самих чанков.

Авторизация

Токен передаётся в заголовке Authorization. Токен выдаётся на проект и отзывается в панели.

Authorization: Bearer kc_live_8f2c41ab9d3e

Сессия загрузки

Перед отправкой чанков откройте сессию. Сервер вернёт идентификатор и рекомендуемый размер части.

POST /api/v1/storage/session

Поле	Тип	Описание
`key`	string	Путь объекта в бакете
`size`	int	Полный размер файла в байтах
`chunk_size`	int	Необязательно. От 262144 до 8388608

// ответ
{
  "session_id": "8f2c41ab",
  "chunk_size": 1048576,
  "chunks_total": 1434,
  "expires_at": "2026-08-20T15:04:05Z"
}

Отправка чанков

Каждая часть уходит отдельным запросом. Порядок значения не имеет, части можно слать параллельно и повторять при обрыве — сервер игнорирует дубликаты.

PUT /api/v1/storage/chunk

Заголовок	Описание
`X-Session-Id`	Идентификатор из ответа на открытие сессии
`X-Chunk-Index`	Порядковый номер части, с нуля
`Content-Length`	Размер части. Последняя часть может быть меньше

Клиенты с нестабильным каналом обычно берут маленький чанк и высокую параллельность — так теряется меньше при обрыве. Мобильные SDK по умолчанию используют 512 КБ и 8 параллельных запросов.

curl -X PUT https://kuralesia.ru/api/v1/storage/chunk \
  -H "X-Session-Id: 8f2c41ab" \
  -H "X-Chunk-Index: 12" \
  --data-binary @part-12.bin

Узнать, какие части уже доехали:

GET /api/v1/storage/chunk?session_id=8f2c41ab

Сборка объекта

После доставки всех частей закройте сессию. Сервер соберёт файл и сверит контрольную сумму.

POST /api/v1/storage/commit

{
  "sha256": "9b1f0c…c4e2"
}

Если сумма не совпала, объект не создаётся, а сессия остаётся открытой до истечения срока — можно перезалить подозрительные части.

Получение файла

GET /api/v1/storage/object/{key}

Поддерживаются Range-запросы и условные заголовки If-None-Match. Публичные объекты отдаются с edge-узлов, приватные — по подписанной ссылке со сроком жизни.

DELETE /api/v1/storage/object/{key}

Лимиты

Параметр	Значение
Размер объекта	до 5 ТБ
Размер чанка	256 КБ — 8 МБ
Жизнь сессии	24 часа
Параллельных запросов на токен	64
Запросов к API	не тарифицируются

Коды ошибок

Код	Причина
`400`	Некорректный индекс части или размер тела
`401`	Токен отсутствует, истёк или отозван
`404`	Сессия не найдена или уже закрыта
`409`	Контрольная сумма не сошлась при сборке
`413`	Часть больше максимального размера чанка
`429`	Превышена параллельность. Повторите с задержкой