Skip to content

API documentation

The API serves one zone. The base URL is the zone's host, for example https://fra.velravio.com. An account created in Frankfurt answers on the Frankfurt host and nowhere else. The current version is v1, under /api/v1. The machine-readable spec is at /api/v1/openapi.json.

The v0 API is gone

/api/v0 was switched off on 30 June 2023. It now returns 410 Gone with a note pointing here. If an old script broke, swap v0 for v1; most paths are otherwise the same.

Authentication

Two ways. An API token goes in the Authorization header; create one in the account console, where the secret is shown once. A cookie session comes from POST /api/v1/auth/login and is what the browser workspace uses.

Authorization header
Authorization: Bearer vrv_XXXXXXXXXXXXXXXXXXXXXXXX

Cookie-session requests that change state must also send X-CSRF-Token (returned by GET /api/v1/me). Bearer-token requests do not need it.

Errors

Every error has the same shape and an X-Request-Id header matching request_id:

{
  "error": { "code": "validation_failed", "message": "Some fields are invalid",
             "fields": { "password": "Use at least 10 characters" } },
  "request_id": "req_8f1c0a2b4d6e8f0a1b2c"
}

Status codes follow the usual meanings: 400 bad_request, 401 unauthorized, 403 forbidden, 404 not_found, 405 method_not_allowed, 409 conflict, 413 payload_too_large, 415 unsupported_media_type, 422 validation_failed, 429 rate_limited. An unknown path under /api/ returns 404 as JSON, not HTML.

Upload a file

Send the bytes as the body of a PUT, with the name in the query string. The response holds the size and SHA-256, and a Digest header repeats the hash.

curl -X PUT \
  -H "Authorization: Bearer $VELRAVIO_TOKEN" \
  -H "Content-Type: image/png" \
  --data-binary @floorplan-rev2.png \
  "https://fra.velravio.com/api/v1/files?name=floorplan-rev2.png"

import requests
with open("floorplan-rev2.png", "rb") as f:
    r = requests.put(
        "https://fra.velravio.com/api/v1/files",
        params={"name": "floorplan-rev2.png"},
        headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "image/png"},
        data=f)
print(r.status_code, r.json()["sha256"])

const body = await file.arrayBuffer();
const r = await fetch(
  "https://fra.velravio.com/api/v1/files?name=" + encodeURIComponent(file.name),
  { method: "PUT",
    headers: { Authorization: `Bearer ${TOKEN}`, "Content-Type": file.type },
    body });
const meta = await r.json();
console.log(meta.sha256);

Download the bytes with GET /api/v1/files/{id}/content. The response is an attachment with the right content type, a Digest header and Accept-Ranges: bytes.

Try it

A live call against this zone. Paste a token (from the console) for the account endpoints, or try the public ones with no token. Nothing is stored by this page; the request goes straight to the API.

The response will show here.

Endpoint reference

Method Path Auth Summary
GET /api/v1/health public Liveness and dependency checks
GET /api/v1/status public Component and per-zone status
GET /api/v1/openapi.json public This spec
POST /api/v1/auth/register public Create an account in a zone
POST /api/v1/auth/login public Start a cookie session
POST /api/v1/auth/logout session End the session
GET /api/v1/me token/session Account, quota, CSRF token
PATCH /api/v1/me token/session Change display name
DELETE /api/v1/me token/session Delete the account and data
POST /api/v1/me/password token/session Change password
GET /api/v1/me/sessions token/session List active sessions
DELETE /api/v1/me/sessions/{id} token/session Revoke a session
GET /api/v1/me/activity token/session Account activity journal
GET/POST /api/v1/tokens token/session List or create API tokens
DELETE /api/v1/tokens/{id} token/session Revoke a token
GET/POST /api/v1/folders token/session List or create folders
PATCH/DELETE /api/v1/folders/{id} token/session Rename, move or trash a folder
GET /api/v1/files token/session List files (sort, name search)
PUT /api/v1/files token/session Upload a file (raw body)
GET /api/v1/files/{id} token/session File metadata
PATCH/DELETE /api/v1/files/{id} token/session Rename, move or trash a file
GET /api/v1/files/{id}/content token/session Download bytes (Range, Digest)
GET /api/v1/trash token/session List trashed files
POST /api/v1/trash/{id}/restore token/session Restore a file
DELETE /api/v1/trash/{id} token/session Delete permanently
GET/POST /api/v1/shares token/session List or create share links
DELETE /api/v1/shares/{id} token/session Revoke a share link
GET /api/v1/shared/{token} public Shared file metadata (code if set)
GET /api/v1/export token/session Download the account as a zip
POST /api/v1/waitlist public Join a paid-plan waitlist
POST /api/v1/contact public Message the team

See also the command-line client for ready-made commands.