REST API reference

#Conventions

• Base URL: https://udrive.one (http://localhost:3000 in development).
• Request and response bodies are JSON. Every input is validated; invalid requests return 400 with { "error": { "code", "message" } }.
• Auth is the udrive_session cookie from SIWS login. Endpoints marked Auth required return 401 without it.
• Mutating requests must be same-origin and are rate-limited per IP and per user (429 with Retry-After when exceeded).
• Responses never include server-only fields (storage keys, IP hashes, raw key material).

#Authentication

Issues a single-use, 5-minute nonce bound to the public key and returns the canonical sign-in message to sign.

Verifies the signed message, consumes the nonce, and sets the session cookie. Body:

Returns the current AccountDTO, or null when signed out.

Clears the session cookie.

#Upload

Validates the file, creates a pending record, and returns a presigned PUT. Body:

Returns { fileId, key, uploadUrl, headers }.

Confirms the object exists, verifies a provenance signature if present, and activates the file. Body:

Returns { shortId, shareUrl }.

#Files

Lists the caller's files. Query params: q, visibility, status, sort (createdAt · name · size · downloadCount), order, limit (1–100), and cursor.

Returns a single owned file as a FileDTO.

Updates mutable fields: name, visibility, allowTraining, trainingPrice, expiresAt.

Soft-deletes the record and removes the object from R2.

Mints a scoped share link. Optional password, expiresAt, maxDownloads. Returns a ShareLinkDTO.

Revokes a share link.

#Download & serve

Runs the access check, increments the counter, logs an anonymized event, and 302-redirects to a fresh presigned attachment URL. Private files require an owner session or a valid share token (and password, if set).

Returns public-safe metadata for the file view page (name, size, type, date, provenance, visibility) — never private internals.

#Provenance

Re-verifies the stored signature against the file and returns a ProvenanceResult ({ signed, verified, signerPubkey, statement }). See Provenance & signing.

#Earnings & marketplace

Returns an EarningsSummaryDTO (totals + history).

Claims the claimable balance. Payout is stubbed: records intent and marks balances claimed without an on-chain transfer yet.

Lists opted-in datasets and simulated training activity.

Generates training events and earnings for opted files (used to make the marketplace feel live in non-production environments).

#Account & API keys

Reads and updates profile + settings: displayName, avatarUrl, bio, and settings (defaultVisibility, dataSharing, trainingPrice).

Lists keys, or creates one. The full key is returned once at creation as ApiKeyCreatedDTO — store it immediately.

Revokes a key.

Danger zone: deletes the account and its files.

#Reporting & stats

Files an abuse report against a shortId with a reason (copyright, illegal, malware, spam, csam, other) and optional details. Heavily rate-limited; reports crossing a threshold auto-quarantine the file.

Public counts for the landing metrics: total files, stored bytes, users, and downloads (StatsDTO).