Справочник

Management API

JSON-API поверх HTTPS для всего, что не относится к данным объектов. Базовый URL: https://api.tcnstorage.store/v1.

Обзор

Аутентификация — Authorization: Bearer <token>.
Списки пагинируются параметром limit (до 200) и непрозрачным cursor.
Изменяющие запросы принимают заголовок Idempotency-Key, он хранится 24 часа.
Лимиты возвращаются в RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. См. лимиты.

Метод	Путь	Описание
GET	/v1/buckets	Список бакетов пространства
POST	/v1/buckets	Создать бакет
GET	/v1/buckets/{name}	Настройки бакета
PATCH	/v1/buckets/{name}	Изменить версии, edge или жизненный цикл
DELETE	/v1/buckets/{name}	Удалить пустой бакет
GET	/v1/keys	Список ключей доступа
POST	/v1/keys	Создать ключ с ограничениями
DELETE	/v1/keys/{id}	Отозвать ключ
POST	/v1/edge/purge	Очистить кеш объектов
POST	/v1/buckets/{name}/notifications	Подписать webhook
GET	/v1/usage	Статистика за расчётный период

Создание бакета

POST /v1/buckets HTTP/1.1
Host: api.tcnstorage.store
Authorization: Bearer tcn_live_4f9c2e7a1b8d
Content-Type: application/json
Idempotency-Key: 7d1f0c9e-2b4a-4e61-9a55-3c8e1f6b2d40

{"name":"media-assets","region":"fra1","versioning":true}

{
  "name": "media-assets",
  "region": "fra1",
  "versioning": "enabled",
  "object_lock": false,
  "edge": { "enabled": false, "hostname": "media-assets.cdn.tcnstorage.store" },
  "created_at": "2026-09-14T10:22:31Z"
}

Ключ с ограничениями

{
  "name": "ci-uploader",
  "scopes": [
    { "bucket": "build-artifacts", "prefix": "releases/", "actions": ["put", "list"] }
  ],
  "expires_at": "2026-12-31T23:59:59Z"
}

{
  "id": "key_01J8ZQ4N2V7R",
  "access_key_id": "TCNK3H8W5P1LEXAMPLE",
  "secret_access_key": "показывается только в этом ответе",
  "expires_at": "2026-12-31T23:59:59Z"
}

Очистка edge-кеша

Очистка по точным URL (до 1 000 за запрос), по префиксам (до 50) или по тегам кеша (до 100). Очистка завершается во всех точках менее чем за две секунды.

Запрос

{
  "bucket": "media-assets",
  "urls": ["https://media-assets.cdn.tcnstorage.store/2026/poster.jpg"],
  "tags": ["campaign-autumn"]
}

Уведомления о событиях

Webhook получает POST на каждое подходящее событие. Проверяйте заголовок TCN-Signature — HMAC-SHA256 от тела запроса с секретом endpoint. Неудачные доставки повторяются 24 часа с экспоненциальной задержкой.

Тело доставки

{
  "id": "evt_01J8ZR9D3K6M",
  "type": "object.created",
  "bucket": "media-assets",
  "region": "fra1",
  "object": { "key": "2026/poster.jpg", "size": 482113, "etag": "\"9b2cf535f27731c974343645a3985328\"" },
  "occurred_at": "2026-09-14T10:24:08Z"
}

Ошибки

Ошибки Management API имеют единый JSON-формат и стабильный code. Указывайте request_id при обращении в поддержку.

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 1200 requests per minute exceeded.",
    "request_id": "req_7Hq2Zt9LbX4p",
    "retry_after": 12
  }
}

HTTP	code	Значение
400	invalid_request	Некорректный JSON или нарушено правило валидации.
401	unauthenticated	Токен отсутствует, истёк или отозван.
403	forbidden	Область токена не разрешает действие.
404	not_found	Ресурса нет в этом пространстве.
409	conflict	Имя занято или конфликт состояния, например удаление непустого бакета.
422	quota_exceeded	Будет превышена квота пространства.
429	rate_limited	Слишком много запросов. Подождите retry_after секунд.
500	internal	Непредвиденная ошибка. Идемпотентные запросы можно повторить.

Коды ошибок S3 API — на странице лимиты и ошибки.