Dropvia
EnglishВойти
API v1

Документация API

HTTP-методы, параметры запросов, модели данных и коды ответов API v1.

Протокол и доступ

Запросы выполняются по HTTPS. Для каждого метода приведены формат запроса, успешные ответы и ошибки. Доступ к файловым операциям ограничен: сейчас публичные запросы возвращают 403 или 404.

Адрес файлового сервера

Адрес файлового сервера и API-ключ авторизации нужно получить в личном кабинете.

DROPVIA_SERVER_URL

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

Сохраните HTTPS-адрес сервера без пути /api/v1 в DROPVIA_SERVER_URL, а API-ключ — в DROPVIA_API_KEY. Примеры добавляют путь /api/v1 и передают ключ в заголовке Authorization: Bearer <api-key>. Переменные задавайте на сервере; ключ не должен попадать в клиентский код. Методы /status и /access-requests не требуют ключа.

Ограничения

Тело запроса /access-requests ограничено 16 384 байтами, включая кодирование данных. Лимиты длины полей приведены в описании метода. Максимальный размер файла и квоты частоты запросов в справочнике не заданы.

Примеры JavaScript предназначены для Node.js 22 (от 22.22) или 24 и новее. Для Python требуется пакет requests. Примеры ответов включают HTTP-код, заголовки и тело, если оно предусмотрено.

POST/upload/{uuid?}

Загрузить файл

Загрузка поддерживает multipart/form-data с полем file и необязательным полем path. Для бинарной загрузки передайте MIME-тип в Content-Type, а name и path — в параметрах URL. UUID в пути необязателен: без него сервер создаёт идентификатор. Если UUID уже занят, ответ — 409. При успешном создании ответ 201 содержит FileResource; Location указывает URL метаданных.

POST /upload/{uuid?}
curl --fail-with-body -X POST "${DROPVIA_SERVER_URL%/}/api/v1/upload/67e55044-10b1-426f-9247-bb680e5fe0c8" \
  -H "Authorization: Bearer $DROPVIA_API_KEY" \
  -F 'file=@./brief.pdf' \
  -F 'path=/projects/brief.pdf'

# Raw binary upload
curl --fail-with-body -X POST "${DROPVIA_SERVER_URL%/}/api/v1/upload/67e55044-10b1-426f-9247-bb680e5fe0c8?name=brief.pdf&path=%2Fprojects%2Fbrief.pdf" \
  -H "Authorization: Bearer $DROPVIA_API_KEY" \
  -H 'Content-Type: application/pdf' \
  --data-binary '@./brief.pdf'

Ответ

201 Created — response.http
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Location: /api/v1/files/67e55044-10b1-426f-9247-bb680e5fe0c8

{
  "id": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "name": "brief.pdf",
  "path": "/projects/brief.pdf",
  "size": 1048576,
  "mimeType": "application/pdf",
  "publicUrl": null,
  "downloadUrl": "/api/v1/download/67e55044-10b1-426f-9247-bb680e5fe0c8",
  "createdAt": "2026-10-28T12:00:00.000Z",
  "modifiedAt": "2026-10-28T12:00:00.000Z"
}

GET/download/{uuid}

Скачать файл

Возвращает содержимое файла по UUID. Ответ 200 содержит байты файла и заголовки Content-Type, Content-Disposition и Content-Length. Запрос Range: bytes=0-1023 возвращает первые 1024 байта с кодом 206 и заголовком Content-Range. Если диапазон не содержит ни одного байта файла, сервер возвращает 416. Для отсутствующего или недоступного файла — 404.

GET /download/{uuid}
curl --fail "${DROPVIA_SERVER_URL%/}/api/v1/download/67e55044-10b1-426f-9247-bb680e5fe0c8" \
  -H "Authorization: Bearer $DROPVIA_API_KEY" \
  -H 'Accept: application/pdf, application/octet-stream' \
  --output brief.pdf

# Optional partial download: add -H 'Range: bytes=0-1023'.

Ответ

200 OK — response.http
HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="brief.pdf"
Accept-Ranges: bytes
Cache-Control: private, no-store
Content-Length: 1048576

[Binary file content]

GET/files/{uuid}

Получить метаданные файла

Возвращает FileResource по UUID. Ответ 200 содержит JSON и ETag. При повторном запросе передайте сохранённый ETag в If-None-Match: если представление не изменилось, сервер вернёт 304 без тела. Для отсутствующего или недоступного файла ответ — 404.

GET /files/{uuid}
curl --fail-with-body -X GET "${DROPVIA_SERVER_URL%/}/api/v1/files/67e55044-10b1-426f-9247-bb680e5fe0c8" \
  -H "Authorization: Bearer $DROPVIA_API_KEY"

# To check a cached version, add -H 'If-None-Match: "file-v1"'.

Ответ

200 OK — response.http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, no-cache
ETag: "file-v1"

{
  "id": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "name": "brief.pdf",
  "path": "/projects/brief.pdf",
  "size": 1048576,
  "mimeType": "application/pdf",
  "publicUrl": null,
  "downloadUrl": "/api/v1/download/67e55044-10b1-426f-9247-bb680e5fe0c8",
  "createdAt": "2026-10-28T12:00:00.000Z",
  "modifiedAt": "2026-10-28T12:00:00.000Z"
}

DELETE/files/{uuid}

Удалить файл

Удаляет файл по UUID. Успешный ответ — 204 без тела; JSON читать не нужно. Для отсутствующего или недоступного файла сервер возвращает 404. Если текущее состояние файла препятствует удалению — 409.

DELETE /files/{uuid}
curl --fail-with-body -X DELETE "${DROPVIA_SERVER_URL%/}/api/v1/files/67e55044-10b1-426f-9247-bb680e5fe0c8" \
  -H "Authorization: Bearer $DROPVIA_API_KEY"

Ответ

204 No Content — response.http
HTTP/1.1 204 No Content
Cache-Control: no-store

POST/shares/{uuid}

Создать ссылку на файл

Создаёт ссылку общего доступа к файлу по UUID. Ответ 201 содержит id ссылки, fileId, publicUrl, createdAt и объект file типа FileResource. В file.publicUrl указана созданная ссылка; Location содержит её URL. Для операции требуется право управления файлом.

POST /shares/{uuid}
curl --fail-with-body -X POST "${DROPVIA_SERVER_URL%/}/api/v1/shares/67e55044-10b1-426f-9247-bb680e5fe0c8" \
  -H "Authorization: Bearer $DROPVIA_API_KEY"

Ответ

201 Created — response.http
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store
Location: /s/cc7ea167-2445-427b-b62c-c97b29085154

{
  "id": "cc7ea167-2445-427b-b62c-c97b29085154",
  "fileId": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "publicUrl": "/s/cc7ea167-2445-427b-b62c-c97b29085154",
  "createdAt": "2026-10-28T12:00:00.000Z",
  "file": {
    "id": "67e55044-10b1-426f-9247-bb680e5fe0c8",
    "name": "brief.pdf",
    "path": "/projects/brief.pdf",
    "size": 1048576,
    "mimeType": "application/pdf",
    "publicUrl": "/s/cc7ea167-2445-427b-b62c-c97b29085154",
    "downloadUrl": "/api/v1/download/67e55044-10b1-426f-9247-bb680e5fe0c8",
    "createdAt": "2026-10-28T12:00:00.000Z",
    "modifiedAt": "2026-10-28T12:00:00.000Z"
  }
}

GET/status

Получить статус сервисов

Возвращает checkedAt и массив services с четырьмя компонентами: API, авторизация и файловые серверы D01 и D02. Для каждого компонента указаны id, state и latencyMs. Значения state: operational или degraded; latencyMs указан в миллисекундах. checkedAt — время формирования снимка в UTC. Сервер повторно использует снимок до 60 секунд. Cache-Control: no-store запрещает хранение ответов в HTTP-кэшах, но не отключает этот серверный снимок.

GET /status
curl --fail-with-body -X GET "${DROPVIA_SERVER_URL%/}/api/v1/status"

Ответ

200 OK — response.http
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "checkedAt": "2026-10-28T12:00:00.000Z",
  "services": [
    {
      "id": "api",
      "state": "operational",
      "latencyMs": 42
    },
    {
      "id": "authentication",
      "state": "operational",
      "latencyMs": 38
    },
    {
      "id": "download-01",
      "state": "operational",
      "latencyMs": 59
    },
    {
      "id": "download-02",
      "state": "operational",
      "latencyMs": 46
    }
  ]
}

POST/access-requests

Отправить заявку на доступ

Принимает JSON с обязательными полями name, email, needs и consent: true. organization необязательно. Максимальная длина в кодовых единицах UTF-16: name — 100, email — 254, organization — 160, needs — 1000. В ответе 201 — id заявки и status: received. Это подтверждение получения запроса; доступ к файловым операциям оно не предоставляет. Запросы с чужим Origin отклоняются с кодом 403.

POST /access-requests
curl --fail-with-body -X POST "${DROPVIA_SERVER_URL%/}/api/v1/access-requests" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Alex Morgan","email":"you@example.com","organization":"Studio North","needs":"Keep project files and share finished work.","consent":true}'

Ответ

201 Created — response.http
HTTP/1.1 201 Created
Content-Type: application/json
Cache-Control: no-store

{
  "id": "a8d66708-61ad-4dc2-a181-a0cb8dc6ad0c",
  "status": "received"
}

Модель файла

FileResource — JSON-объект с метаданными файла. Он возвращается при загрузке, получении метаданных и в поле file при создании ссылки. size указан в байтах, временные метки — в UTC. У файла без общего доступа publicUrl равен null. Относительные URL в примерах разрешаются относительно адреса файлового сервера.

FileResource — file.json
{
  "id": "67e55044-10b1-426f-9247-bb680e5fe0c8",
  "name": "brief.pdf",
  "path": "/projects/brief.pdf",
  "size": 1048576,
  "mimeType": "application/pdf",
  "publicUrl": null,
  "downloadUrl": "/api/v1/download/67e55044-10b1-426f-9247-bb680e5fe0c8",
  "createdAt": "2026-10-28T12:00:00.000Z",
  "modifiedAt": "2026-10-28T12:00:00.000Z"
}
idstring · uuid
Идентификатор файла в формате UUID.
namestring
Имя файла, включая расширение, если оно есть.
pathstring
Логический путь в хранилище пользователя, включая имя файла. Например, /projects/brief.pdf.
sizeinteger
Размер содержимого в байтах. Неотрицательное целое число.
mimeTypestring
MIME-тип содержимого, например application/pdf.
publicUrlstring | null
Ссылка общего доступа. Значение null, если общий доступ не включён.
downloadUrlstring
URL метода скачивания. Для запроса требуется авторизация.
createdAtstring · date-time
Время создания записи файла. Строка ISO 8601 в UTC.
modifiedAtstring · date-time
Время последнего изменения. Строка ISO 8601 в UTC; не раньше createdAt.

Расшифровка ошибок

Тело ошибки содержит error.code, error.message и requestId. Для обработки используйте HTTP-код и error.code; при обращении в поддержку передайте requestId. В примерах 401 содержит WWW-Authenticate, 405 — Allow, 416 — Content-Range, 429 и 503 — Retry-After. Проверяйте HTTP-код до чтения JSON или записи скачиваемого файла.

400
Неверный синтаксис запроса, некорректный JSON или UUID.
401
Bearer-токен отсутствует или недействителен. Проверьте Authorization.
403
Операция запрещена. Для заявки код ORIGIN_NOT_ALLOWED означает недопустимый источник запроса.
404
Файл не найден или недоступен для текущего запроса.
405
HTTP-метод не поддерживается для этого URL. Допустимые методы указаны в Allow.
409
UUID уже занят или текущее состояние ресурса препятствует операции.
413
Размер тела запроса превышает допустимый лимит.
415
Тип тела запроса в Content-Type не поддерживается.
416
Диапазон из Range не может быть выдан. Content-Range содержит размер файла.
422
Поля запроса не прошли проверку. Проверьте обязательные значения, форматы и длину.
429
Превышен лимит частоты запросов. Retry-After указывает задержку перед повтором.
500
Ошибка обработки запроса на сервере. Передайте requestId в поддержку.
503
Сервис временно недоступен. Retry-After указывает задержку перед повтором.

HTTP Semantics · RFC 9110