Dropvia
РусскийSign in
API v1

API reference

HTTP methods, request parameters, data models and response codes for API v1.

Protocol and access

Send requests over HTTPS. Each method documents the request format, success responses and errors. File operations are restricted: public requests currently return 403 or 404.

File server address

Get the file server address and authorization API key from your account dashboard.

DROPVIA_SERVER_URL

Authentication

Set DROPVIA_SERVER_URL to the HTTPS server address without /api/v1, and set DROPVIA_API_KEY to your API key. Examples append /api/v1 and send the key in Authorization: Bearer <api-key>. Set these variables on the server and keep the key out of client code. /status and /access-requests require no key.

Limits

The /access-requests body is limited to 16,384 bytes, including data encoding. Field length limits are listed with the method. Maximum file sizes and request rate quotas are not specified in this reference.

JavaScript examples require Node.js 22 (22.22 or later) or version 24 and above. Python examples require the requests package. Response examples include the HTTP status, headers and a body where applicable.

POST/upload/{uuid?}

Upload a file

Upload multipart/form-data with a file field and an optional path field. For a binary upload, set Content-Type to the file MIME type and pass name and path as URL query parameters. The UUID path parameter is optional; the server generates an ID when omitted. An existing UUID returns 409. A successful creation returns 201 with FileResource; Location identifies the metadata 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'

Response

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}

Download a file

Returns file contents by UUID. A 200 response contains file bytes and Content-Type, Content-Disposition and Content-Length headers. Range: bytes=0-1023 requests the first 1024 bytes with status 206 and Content-Range. A range with no overlap with the file returns 416. A missing or inaccessible file returns 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'.

Response

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}

Get file metadata

Returns FileResource by UUID. The 200 response contains JSON and an ETag. Send the saved ETag in If-None-Match on a later request; an unchanged representation returns 304 with no body. A missing or inaccessible file returns 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"'.

Response

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}

Delete a file

Deletes a file by UUID. Success returns 204 with no body; do not parse it as JSON. A missing or inaccessible file returns 404. A file state that prevents deletion returns 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"

Response

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

POST/shares/{uuid}

Create a share link

Creates a public share link for a file UUID. The 201 response contains the link id, fileId, publicUrl, createdAt and a file object of type FileResource. file.publicUrl and Location contain the new share URL. The operation requires permission to manage the file.

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"

Response

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

Get service status

Returns checkedAt and a services array with four components: API, authentication, and file servers D01 and D02. Each component has id, state and latencyMs. state is operational or degraded; latencyMs is in milliseconds. checkedAt is the snapshot generation time in UTC. The server reuses a snapshot for up to 60 seconds. Cache-Control: no-store prevents HTTP caches from storing responses; it does not disable this server-side snapshot.

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

Response

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

Submit access request

Accepts JSON with required name, email, needs and consent: true fields. organization is optional. Maximum lengths in UTF-16 code units: name 100, email 254, organization 160, needs 1000. The 201 response contains the request id and status: received. It acknowledges receipt and does not grant file access. Requests with a foreign Origin return 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}'

Response

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"
}

File model

FileResource is a JSON object containing file metadata. Upload and metadata methods return it; share responses include it in the file field. size is in bytes and timestamps use UTC. A file without public sharing has publicUrl: null. Resolve relative URLs in the examples against the file server address.

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
File identifier in UUID format.
namestring
Filename, including the extension if present.
pathstring
Logical path in the user storage space, including the filename. For example, /projects/brief.pdf.
sizeinteger
Content size in bytes. A non-negative integer.
mimeTypestring
Content MIME type, such as application/pdf.
publicUrlstring | null
Public share URL. null when public sharing is disabled.
downloadUrlstring
Download endpoint URL. Requests require authorization.
createdAtstring · date-time
File record creation time as an ISO 8601 UTC string.
modifiedAtstring · date-time
Last modification time as an ISO 8601 UTC string; not earlier than createdAt.

Error reference

Error bodies contain error.code, error.message and requestId. Handle errors using the HTTP status and error.code; include requestId when contacting support. The examples include WWW-Authenticate for 401, Allow for 405, Content-Range for 416 and Retry-After for 429 and 503. Check the HTTP status before parsing JSON or writing downloaded bytes.

400
Malformed request syntax, invalid JSON or an invalid UUID.
401
Bearer token missing or invalid. Check Authorization.
403
Operation forbidden. For access requests, ORIGIN_NOT_ALLOWED indicates a disallowed request origin.
404
File not found or inaccessible to this request.
405
HTTP method unsupported for this URL. See Allow for permitted methods.
409
The UUID already exists or the resource state prevents the operation.
413
Request body exceeds the permitted size.
415
The request Content-Type is not supported.
416
The requested Range cannot be satisfied. Content-Range indicates the file size.
422
Request fields failed validation. Check required values, formats and length limits.
429
Request rate limit exceeded. Retry-After specifies the delay before retrying.
500
Server error while processing the request. Include requestId when contacting support.
503
Service temporarily unavailable. Retry-After specifies the delay before retrying.

HTTP Semantics · RFC 9110