Skip to content
Back to Sturm

File API

Plain HTTPS, nothing fancy. You need keys to push, you only need the link to pull.

Base URL

Everything sits under https://sturmv1.lol/api/v1. Good calls return { data, requestId }. Bad calls return application/problem+json with a code and the requestId. Send that ID when you complain.

GET /api/v1/health, GET /api/v1/capabilities, and GET /api/v1/openapi.json stay open with zero credentials. Check the capabilities before you push anything.

Response envelope

{
  "data": { "status": "ok" },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Error response

{
  "type": "urn:sturm:error:file_not_found",
  "title": "FILE_NOT_FOUND",
  "status": 404,
  "code": "FILE_NOT_FOUND",
  "detail": "File is not available.",
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Authentication

Management calls take two headers over HTTPS. Never put keys in a URL. One pair opens every endpoint below:

Sturm-Access-Key: <access-key>
Sturm-Secret-Key: <secret-key>

Python

import os
import requests

response = requests.get(
    "https://sturmv1.lol/api/v1/me",
    headers={
        "Sturm-Access-Key": os.environ["STURM_ACCESS_KEY"],
        "Sturm-Secret-Key": os.environ["STURM_SECRET_KEY"],
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"])

Node.js

const response = await fetch("https://sturmv1.lol/api/v1/me", {
  headers: {
    "Sturm-Access-Key": process.env.STURM_ACCESS_KEY,
    "Sturm-Secret-Key": process.env.STURM_SECRET_KEY,
  },
  redirect: "error",
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error("API request failed (" + response.status + ")");
console.log(await response.json());

Response

{
  "data": {
    "id": "7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
    "status": "active",
    "maxFileBytes": 1073741824,
    "version": 3,
    "createdAt": 1790812800000
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Upload

Every upload rides one encrypted resumable session, straight to storage, with progress, pause, and resume, for files up to 1,07 GB:

POST   /api/v1/uploads                 Start a session
GET    /api/v1/uploads/<uuid>          Session state
POST   /api/v1/uploads/<uuid>/parts    Sign part URLs
POST   /api/v1/uploads/<uuid>/complete Finish upload
DELETE /api/v1/uploads/<uuid>          Abort session

Sessions use asynchronous 202 responses; poll until the session is ready before sharing its UUID link. Use the OpenAPI spec for exact schemas.

Session descriptor

{
  "data": {
    "id": "7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
    "size": 1073741824,
    "name": "archive.bin",
    "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
     "key": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=",
    "state": "uploading",
    "parts": [1, 2],
    "verifiedFrames": 64,
    "expiresAt": 1789000000000
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Files

GET    /api/v1/files?limit=25             List my files
GET    /api/v1/files/<uuid>              My file metadata
GET    /api/v1/files/<uuid>/content      File bytes (public)
GET    /api/v1/files/<uuid>/view         Preview metadata (public)
PATCH  /api/v1/files/<uuid>              Update metadata
DELETE /api/v1/files/<uuid>              Delete file

Listing takes limit (1–200, default 25), a cursor, and status (uploading, ready, deleting, deleted, failed). Skip status and the list hides deleted and failed rows. Feed the cursor back as ?cursor= until nextCursor turns null. Read the cursor, hand it back, never build one. You only see your own files.

Patch metadata with JSON and put the current quoted version in If-Match, the same number the ETag header hands you. A stale version eats 412 VERSION_CONFLICT, and a delete bumps the version too, so it kills any If-Match you were still holding. Deletes land a 202 with { id, status: "deleting", jobId }. The bytes die off in the background.

updatedAt moves on any write: metadata edits, upload progress, deletions. uploadState and uploadUpdatedAt come back only from GET /api/v1/files/<uuid>, so the list above always nulls them. Poll the single file to watch a segmented upload move.

Response

{
  "data": [
    {
      "id": "7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
      "ownerId": "7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
      "bucketId": "7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
      "name": "file.txt",
      "mime": "text/plain",
      "size": 1234,
      "status": "ready",
      "version": 1,
      "createdAt": "2026-10-01T00:00:00.000Z",
      "updatedAt": "2026-10-01T00:00:00.000Z",
      "url": "https://sturmv1.lol/7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
      "uploadState": null,
      "uploadUpdatedAt": null
    }
  ],
  "page": { "limit": 25, "nextCursor": null },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Download

Hit https://sturmv1.lol/:uuid to view in the browser, add ?download to keep the original file. Old /f/:uuid links still work. No login.

The browser decrypts and checks the full SHA-256 before it hands anything over. Python and Node.js clients with no browser pull raw bytes from the content endpoint, check the SHA-256 from the view endpoint, or run the verified CLI download for segmented files.

Segmented files use a different shape: GET /api/v1/files/<uuid>/download hands back the base64 file key, the digest, and a short-lived storage URL. It is public on purpose. Holding the UUID already means holding the file, so gating that call would only push the key one step further down the client instead of locking anything.

The host can unwrap file keys. This is encrypted storage, not end-to-end encryption. Large browser downloads stage plaintext in private browser storage before verification finishes. Cleanup is best effort and cannot guarantee erasure after a crash; use a trusted device.

Response

{
  "data": {
    "id": "7e9c6a1b-4d2f-4a8e-9c1b-2d3e4f5a6b7c",
    "name": "file.txt",
    "mime": "text/plain",
    "size": 1234,
    "digest": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "mode": "legacy"
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Rotation and errors

The Revocation Key trades your Access + Secret pair for a fresh one. Send it in the Sturm-Revocation-Key header with an empty body plus a mandatory Sturm-Idempotency-Key. Reuse that same key on retries: replaying a recorded operation does not spend another rotation. A new request key is a new operation. Old links stay alive.

You get 3 rotations per account. A 4th returns ROTATION_LIMIT_REACHED and leaves keys alone. Push once more and the account is gone (ACCOUNT_DELETED).

Response

{
  "data": {
    "accessKey": "sturm_0123456789abcdef0123456789abcdef0123456789abcdef",
    "secretKey": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

OpenAPI spec for contracts, params, headers, and responses.