Skip to content

API Overview ​

SkySend exposes a REST API under the /api prefix. All endpoints accept and return JSON unless otherwise noted. A route that reads a JSON body needs Content-Type: application/json and answers 415 to any other type, so another site cannot send it as a simple request without a CORS preflight.

Base URL ​

http://localhost:3000/api

Endpoints ​

File Endpoints ​

MethodPathDescriptionAuth
GET/api/configServer configuration (limits)-
GET/api/quotaUpload quota status for the client IP-
POST/api/uploadUpload encrypted file stream-
POST/api/upload/initInitialize chunked upload session-
POST/api/upload/:id/chunkAppend chunk (with ?index=N)-
POST/api/upload/:id/finalizeFinalize chunked uploadOwner Token
POST/api/meta/:idSave encrypted metadataOwner Token
GET/api/info/:idUpload info (size, expiry, downloads)-
GET/api/download/:idDownload encrypted file streamAuth Token
POST/api/password/:idVerify file password-
DELETE/api/upload/:idDelete uploadOwner Token
GET/api/exists/:idCheck if upload exists-
GET/api/healthHealth check-

Note Endpoints ​

MethodPathDescriptionAuth
POST/api/noteCreate encrypted note-
GET/api/note/:idNote info (type, views, expiry)-
POST/api/note/:id/viewView note (returns encrypted content)Auth Token
POST/api/note/:id/passwordVerify note password-
DELETE/api/note/:idDelete noteOwner Token

File Request Endpoints ​

Active when request is in ENABLED_SERVICES. See File Requests.

MethodPathDescriptionAuth
POST/api/requestCreate a file requestOIDC when OIDC_PROTECT_REQUESTS
GET/api/request/limitNew requests the caller has left todayOIDC when OIDC_PROTECT_REQUESTS
GET/api/request/:idWhat a sender seesUpload Token
GET/api/request/:id/upload/wsWebSocket upload into the requestUpload Token in the init frame
POST/api/request/:id/upload/initOpen an upload into the requestUpload Token
POST/api/request/:id/upload/:uid/chunkAppend chunk (with ?index=N)Upload session
POST/api/request/:id/upload/:uid/finalizeStore the upload with its wrapped keyUpload session
DELETE/api/request/:id/upload/:uidCancel an upload and free its slotUpload session
GET/api/inbox/:idVault and uploads of the inboxInbox Token
GET/api/inbox/:id/file/:uidDownload one uploadInbox Token
DELETE/api/inbox/:id/file/:uidDelete one uploadInbox Owner Token
POST/api/inbox/:id/closeStop new uploadsInbox Owner Token
DELETE/api/inbox/:idDelete the request and its uploadsInbox Owner Token

OIDC Auth Endpoints ​

These routes are only active when OIDC is configured (i.e., when OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET are all set). They live outside the /api prefix.

MethodPathDescriptionAuth
GET/auth/loginStart PKCE login, redirect to provider-
GET/auth/callbackHandle provider callback, issue session-
GET/auth/logoutClear session, redirect to provider end-sessionSession cookie
GET/auth/sessionReturn current user infoSession cookie / Bearer

See OIDC Authentication for the full flow and access-control details.

Authentication ​

SkySend uses two token types, both derived from the client-side secret:

Auth Token (X-Auth-Token) ​

Required for downloading files. Derived from the secret via HKDF + HMAC-SHA256. Proves the requester knows the encryption key.

Owner Token (X-Owner-Token) ​

Required for deleting uploads and saving metadata. Derived from the secret via HKDF. Proves upload ownership.

Both tokens are provided as base64url-encoded strings in request headers.

Common Response Codes ​

CodeMeaning
200Success
400Invalid request (missing/invalid parameters)
401Invalid or missing auth token
404Upload not found, or an unknown path under /api ({"error": "Not found"})
409Conflict (e.g., metadata already set)
405HEAD on a route that counts a download
410Upload expired or download limit reached
415A JSON body sent without Content-Type: application/json
429Rate limit or quota exceeded
500Internal server error

Rate Limiting ​

All endpoints are rate-limited. Response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1704067260000

Server Configuration ​

GET /api/config ​

Returns server limits and options for the client UI. Each field comes from the environment variable of the same name.

enabledServices lists file and note only. File requests are reported as fileRequestsEnabled, because CLI clients before v4 refuse a config whose enabledServices holds anything else.

Response:

json
{
  "enabledServices": ["file", "note"],
  "fileMaxSize": 2147483648,
  "fileMaxFilesPerUpload": 200,
  "fileExpireOptions": [300, 3600, 86400, 604800],
  "fileDefaultExpire": 86400,
  "fileDownloadOptions": [1, 2, 3, 4, 5, 10, 20, 50, 100],
  "fileDefaultDownload": 1,
  "fileUploadQuotaBytes": 0,
  "fileUploadQuotaWindow": 86400,
  "fileUploadConcurrentChunks": 3,
  "fileUploadSpeedLimit": 0,
  "fileUploadWs": true,
  "fileRequestsEnabled": true,
  "fileRequestExpireOptions": [86400, 259200, 604800],
  "fileRequestDefaultExpire": 259200,
  "fileRequestUploadOptions": [1, 2, 3, 5, 10, 20, 50, 100],
  "fileRequestDefaultUploads": 10,
  "fileRequestMaxSize": 2147483648,
  "fileRequestRetention": 604800,
  "fileRequestDownloadOptions": [1, 2, 3, 5, 10, 20],
  "fileRequestDefaultDownloads": 5,
  "noteMaxSize": 1048576,
  "noteExpireOptions": [300, 3600, 86400, 604800],
  "noteDefaultExpire": 86400,
  "noteViewOptions": [0, 1, 2, 3, 5, 10, 20, 50, 100],
  "noteDefaultViews": 0,
  "noteBlocks": true,
  "customTitle": "SkySend",
  "customColor": null,
  "customLogo": null,
  "customPrivacy": null,
  "customLegal": null,
  "customLinkUrl": null,
  "customLinkName": null,
  "customReportUrl": null,
  "defaultTheme": "graphite",
  "defaultColorScheme": "system",
  "defaultTab": "file",
  "forceFilePassword": false,
  "forceNotePassword": false,
  "forceRequestPassword": false,
  "oidcEnabled": false,
  "oidcProtectFiles": false,
  "oidcProtectNotes": false,
  "oidcProtectRequests": false
}

noteBlocks is true on servers that accept notes made of blocks, which is every server since v3. A client checks it before it creates such a note and falls back to a legacy content type on an older server, where the field is missing.

Health Check ​

GET /api/health ​

Simple health check for monitoring and Docker health checks.

Response:

json
{
  "status": "ok",
  "version": "2.11.3",
  "timestamp": "2025-01-01T00:00:00.000Z"
}