Справочник · v1

API Findes

Базовый URL: https://findes.download/api/v1 · ответы в JSON · загрузка и скачивание стримингом. Полная спецификация OpenAPI 3.1 доступна в консоли: Проект → API → Спецификация.

Быстрый старт

# 1) отправить пакет логов
curl -sS -H "Authorization: Bearer $FINDES_TOKEN" \
     -H "Content-Type: application/x-ndjson" \
     --data-binary @events.ndjson \
     https://findes.download/api/v1/logs

# 2) загрузить бэкап (любой размер, продолжаемая загрузка)
curl -sS -H "Authorization: Bearer $FINDES_TOKEN" \
     -T backup-2026-10-19.tar \
     "https://findes.download/api/v1/backups?project=prod-db"

# 3) скачать архив
curl -sSL -H "Authorization: Bearer $FINDES_TOKEN" \
     -o restore.tar https://findes.download/api/v1/archives/ar_1a2b3c4d5e

Аутентификация

Все запросы требуют токен, выпущенный в консоли (Настройки → API-токены). Токен привязан к проекту и может быть ограничен только загрузкой или только скачиванием. Токен передаётся в заголовке Authorization:

Authorization: Bearer fin_live_xxxxxxxxxxxxxxxx

Токен равнозначен паролю. Рекомендуется ротация раз в 90 дней; отзыв действует немедленно.

Приём логов

POST /logs

Добавляет пакет log-событий. Тело — JSON через перевод строки (NDJSON) или простой текст с параметром source. Подтверждение приходит, когда пакет надёжно записан в буфер.

Параметр	Где	Описание
`source`	query	Имя источника, например `nginx-access`, `app.worker.1`. По умолчанию — проект токена.
`host`	query	Имя хоста. Если не указано, берётся от агента.
`Content-Type`	header	`application/x-ndjson` или `text/plain`.

Ответ 201 Created

{
  "id": "lg_7f3ac91b2d",
  "received": 1048576,
  "events": 1204,
  "source": "nginx-access",
  "retentionDays": 30,
  "status": "accepted"
}

Загрузка бэкапа

POST /backups

Загружает архив бэкапа любого размера. Загрузка идёт кусками и продолжаема: прерванную сессию можно докачать в течение 48 часов по её id.

Параметр	Где	Описание
`project`	query	Проект назначения. Обязателен, если токен не привязан к проекту.
`X-Findes-Retention-Days`	header	Переопределить срок хранения для этого архива (не выше максимума проекта).
`X-Findes-Checksum-Sha256`	header	Необязательный SHA-256 тела в hex; проверяется сервером после загрузки.

Ответ 201 Created

{
  "id": "ar_1a2b3c4d5e",
  "project": "prod-db",
  "received": 272629760,
  "compressedBytes": 272631808,
  "retentionDays": 90,
  "status": "sealed"
}

Скачивание архива

GET /archives/{id}

Отдаёт архив потоком как application/octet-stream (контейнер gzip). Поддерживаются диапазоны байт для частичного восстановления. Расшифровка происходит на лету, данные не пишутся на диск сервера.

Параметр	Где	Описание
`id`	path	Идентификатор архива, например `ar_1a2b3c4d5e`.
`Range`	header	Необязательный диапазон, например `bytes=0-1048575`.

Манифест архива

GET /archives/{id}/manifest

Метаданные архива без скачивания самого архива.

{
  "id": "ar_1a2b3c4d5e",
  "project": "prod-db",
  "size": 272629760,
  "compressedBytes": 272631808,
  "compression": "gzip",
  "encrypted": true,
  "objects": 148,
  "created": "2026-10-19T02:15:44Z",
  "expires": "2027-01-17T02:15:44Z",
  "checksum": "sha256:9f2c…e41a"
}

Статус сервиса

GET /status

Публичный статус компонентов без аутентификации. Используется также страницей статуса.

Лимиты

Категория	Ограничение
Управляющие запросы	60 в минуту на токен
Параллельные потоки загрузки/скачивания	2 на токен
Повышение лимитов	по запросу на support@findes.download

При превышении возвращается 429 с заголовком Retry-After.

Агенты

Утилита findes-agent (Linux, macOS, Windows) доступна на странице загрузок в консоли. Сторонние сборщики подключаются напрямую:

# вывод fluent-bit
[OUTPUT]
    Name        http
    Match       *
    Host        findes.download
    Port        443
    TLS         On
    URI         /api/v1/logs
    Format      json_lines
    Header      Authorization Bearer $FINDES_TOKEN

Ошибки

Код	Значение	Описание
400	`bad_request`	Некорректные параметры или тело.
401	`invalid_credentials`	Токен отсутствует, отозван или истёк.
403	`forbidden`	У токена нет нужных прав.
404	`not_found`	Неизвестный ресурс.
429	`rate_limited`	См. `Retry-After`.

История изменений

Версия	Дата	Изменения
1.4.2	2026-09-08	В манифест добавлено поле `checksum`.
1.4.0	2026-07-21	Продолжаемые загрузки; сессии на 48 часов.
1.3.0	2026-05-02	Скачивание диапазонами байт.
1.2.0	2026-02-16	Заголовок переопределения хранения для загрузки.