# RelayBox API reference

Base URL: https://file.leezhu.cn
Machine-readable OpenAPI: https://file.leezhu.cn/openapi.json
Complete Agent instructions: https://file.leezhu.cn/skill
CLI source: https://file.leezhu.cn/relaybox.mjs

Public documentation is intentionally readable without authentication. Files remain private.

## Agent endpoints (Bearer token)
GET /api/files?q=&limit=&offset= — list/search; files:read
GET or HEAD /api/files/{id}/download — attachment/range download; files:read
DELETE /api/files/{id} — permanent delete; files:delete
POST /api/uploads — reserve quota and begin; files:write
GET /api/uploads/{id} — uploaded-part status; files:write
PUT /api/uploads/{id}/parts/{number} — exact raw part; files:write
POST /api/uploads/{id}/complete — finalize file; files:write
DELETE /api/uploads/{id} — abort unfinished upload; files:write

Agent token is supplied only in Authorization: Bearer <TOKEN>.
Do not put credentials in URLs or follow redirects when sending Authorization.
Agent tokens are scoped, expiring and revocable; file-scoped tokens cannot upload.

## Owner browser endpoints (HttpOnly session)
GET /api/auth/session — public readiness/session state, configured flag and limits
POST /api/auth/login — {password}; same Origin required
POST /api/auth/logout — current session + Origin + X-CSRF-Token
GET /api/tokens — metadata only; never returns existing token secrets
POST /api/tokens — {name,scopes,fileId?,expiresInDays?}; token shown once
DELETE /api/tokens/{id} — revoke
GET /api/files/{id}/shares — share metadata
POST /api/files/{id}/shares — {password?,expiresInHours?}; secret URL shown once
DELETE /api/shares/{id} — revoke

Cookie mutation requests require matching Origin and X-CSRF-Token returned by login/session. Agent tokens cannot manage tokens/shares. Owners enter credentials and approve persistent grants personally.

## Share endpoints
GET /api/share/{secret} — public link metadata/password requirement
POST /api/share/{secret}/access — {password}; same Origin, short-lived HttpOnly share cookie
GET or HEAD /api/share/{secret}/download — unprotected or unlocked share download
Share UI: /s/{secret}
Share secrets are access credentials; never log them. Optional passwords are8+characters; expiry is capped by the file's expiry. A link holder may see filename/size before unlocking. Revocation/expiry blocks new access immediately.

## Payloads and limits
File metadata: id,name,size,mimeType,createdAt,expiresAt (Unix seconds)
Upload begin: {name,size,mimeType?,expiresInDays?}
Upload begin201: {ok:true,uploadId,fileId,partSize,totalParts,expiresAt}
Upload status: {ok:true,uploadId,fileId,name,size,status,partSize,totalParts,parts:[{partNumber,size}],expiresAt}
Upload complete200: {ok:true,file:{...metadata}}
List200: {ok:true,files:[...],total,quota:{used,reserved,limit}}; quota:null for file-scoped tokens
Error: {ok:false,error:{code,message}}

Maximum2GiB/file;32MiB parts;20GiB default total quota including reservations.
Default file retention7days, configurable1–30days. Upload session24hours.
Token expiry1hour–90days, default30days. Share expiry15minutes–30days, never after file expiry.

Common statuses:400 invalid request,401 unauthenticated,403 forbidden,404 expired/missing,409 conflict/quota,413 oversized,416 invalidRange,421 wrongorigin,429 ratelimited,503 ownernotconfigured or transientfailure.

If GET /api/auth/session reports configured:false, the owner must personally finish setup at https://file.leezhu.cn/setup.html and save the derived value as Cloudflare Secret MASTER_PASSWORD_HASH. Do not send the password/hash to the assistant. This documentation remains usable while private APIs are locked.