OVERVIEW

Upload, download, manage, and delete files programmatically over HTTPS. All endpoints use the base URL shown below.

Guest uploads are temporary and expire automatically. Authenticated users can upload to their cloud drive with optional permanent retention.

BASE URL
https://one.gy
MAX UPLOAD SIZE
5 GB
GUEST UPLOAD LIMIT
1 GB
DEFAULT EXPIRY
1 DAY
ENCRYPTION
FERNET (AT REST)

UPLOAD

POST
/upload

Upload one or more files via multipart form data. Returns a management URL and a download URL. Multiple files are automatically bundled into a ZIP archive server-side.

Guest uploads are temporary and expire after 1 day by default. Authenticated users can upload to their cloud drive by setting is_temp=false for permanent retention.

EXAMPLES

PARAMETERS

NAME TYPE DESCRIPTION
files file One or more files (multipart/form-data). Use file for single E2E uploads.
is_temp string "true" (default) for temporary upload, "false" for cloud drive (requires login)
folder_id integer Destination folder ID for cloud drive uploads (requires login)
short_url string "true" to generate a short 6-character URL code accessible at /s/{code}
e2e string "true" for client-side encrypted uploads (see E2E section)
e2e_salt string Base64 or comma-separated decimal bytes of 16-byte salt (required if e2e=true)
e2e_iv string Base64 or comma-separated decimal bytes of 12-byte IV (required if e2e=true)

RESPONSE

DOWNLOAD

GET
/f/{file_id}/{filename}

Download a file by its UUID. Including the filename in the URL ensures wget and curl -O save with the correct name. Password-protected files require the pw query parameter.

Files uploaded with short_url=true can also be downloaded via /s/{short_code}, which redirects to the full URL (or serves directly for CLI clients).

EXAMPLES

PARAMETERS

NAME TYPE DESCRIPTION
file_id path UUID of the file
filename path Original filename (optional, ensures correct save name)
pw query Password for protected files

RESPONSE

MANAGE FILE

GET
/manage/{token}

View file management page. The management token is returned in the upload response under redirect. Requires session ownership.

POST
/manage/{token}

Update file settings programmatically. Set the X-Requested-With: XMLHttpRequest header to receive a JSON response instead of a redirect.

EXAMPLES

PARAMETERS

NAME TYPE DESCRIPTION
public string "on" to make file publicly accessible, "off" to make private
expires string 30m, 6h, 1d, 3d, 7d, or never. never requires a logged-in user with a cloud drive file; temp/guest uploads are capped at 7d.
max_downloads integer Max total downloads before file is auto-deleted. Set to 0 to remove the limit.

RESPONSE

DELETE FILE

POST
/delete/{token}

Permanently delete a file from the server. Requires the management token and session ownership. The token is the last segment of the management URL returned during upload.

EXAMPLES

RESPONSE

E2E ENCRYPTION

End-to-end encrypted files are encrypted on the client before upload. The server never sees the plaintext data or the encryption key.

BROWSER & CLI (MODERN): The browser and CLI tool use a MEGA-style zero-knowledge system with per-file AES-256-GCM keys, chunked 64MB encryption, and PBKDF2 key derivation with 600,000 iterations. This is handled automatically and is not directly accessible via the API examples below.

API (LEGACY SIMPLE): The examples below demonstrate a simpler single-file encryption scheme using AES-256-GCM with PBKDF2 key derivation (600,000 iterations). You derive a key from a passphrase using PBKDF2 with a random salt, encrypt the file with AES-256-GCM using a random IV, then upload the ciphertext along with the salt and IV as form parameters.

UPLOAD WITH E2E ENCRYPTION

POST
/upload

DOWNLOAD AND DECRYPT E2E FILE

GET
/f/{file_id}/encrypted

Download raw encrypted data for E2E files. The response includes X-E2E-Salt and X-E2E-IV headers containing comma-separated decimal byte values of the salt and IV needed for decryption.

E2E PARAMETERS

NAME TYPE DESCRIPTION
e2e string "true" to mark upload as end-to-end encrypted
e2e_salt string Comma-separated decimal byte values of 16-byte salt used for PBKDF2 key derivation (e.g. "142,55,201,44,..."). Base64-encoded strings are also accepted.
e2e_iv string Comma-separated decimal byte values of 12-byte IV used for AES-256-GCM encryption (e.g. "10,233,78,..."). Base64-encoded strings are also accepted.

RESPONSE HEADERS (ENCRYPTED DOWNLOAD)

HEADER TYPE DESCRIPTION
X-E2E-Salt string Comma-separated decimal byte values of salt for PBKDF2 key derivation
X-E2E-IV string Comma-separated decimal byte values of IV for AES-256-GCM decryption

AUTHENTICATION

All authenticated API endpoints require an API key sent via the Authorization header using the Bearer scheme. Generate API keys from your account page.

Each API key has individual permissions controlling which actions it can perform. You can also restrict keys to specific IP addresses. Users can create up to 10 API keys, each with their own permissions and IP whitelist.

AUTHENTICATION HEADER

PERMISSIONS

Each API key must be granted specific permissions. All permissions are disabled by default when creating a new key. Available permissions:

PERMISSION ENDPOINTS DESCRIPTION
read GET /apiv1/files, /search, /trash, /files/{id}/properties List files, folders, search, view trash, get file properties
download GET /apiv1/download/{id} Download files
write POST /apiv1/upload, /folders Upload files, create folders
delete DELETE /apiv1/files/{id}, /folders/{id}, /trash/{id}, /trash/empty Trash and permanently delete files/folders, empty trash
restore POST /apiv1/trash/{id}/restore Restore files from trash
manage_keys GET/POST/PATCH/DELETE /apiv1/keys List, create, update, and revoke API keys via the API

IP WHITELIST

Each API key can optionally be restricted to a list of up to 10 IPv4 addresses or CIDR subnets (minimum /24). If no IPs are configured, the key works from any IP address.

EXAMPLE

ERROR RESPONSES

CODE REASON DESCRIPTION
401 Missing/Invalid Key No Authorization header, invalid format, or revoked/unknown key
403 API Disabled / No Permission / IP Blocked API access disabled, key lacks required permission, or IP not in whitelist

KEY MANAGEMENT (API)

POST
/apiv1/keys

Create a new API key with specific permissions and optional IP whitelist. Requires manage_keys permission. Maximum 10 active keys per user.

REQUEST BODY

EXAMPLE

PATCH
/apiv1/keys/{key_id}

Update permissions, IP whitelist, and/or label on an existing API key. Only provided fields are changed.

EXAMPLE

RESPONSE

UPLOAD (API)

POST
/apiv1/upload

Upload a file to your cloud drive. Files are encrypted server-side with Fernet (E2E encryption is not supported via API). Uploaded files have no expiration and are private by default.

EXAMPLES

PARAMETERS

NAME TYPE DESCRIPTION
file / files file One or more files (multipart/form-data). Use file for single, files for multiple.
folder_id integer Destination folder ID (optional, defaults to root)

RESPONSE

DOWNLOAD (API)

GET
/apiv1/download/{file_id}

Download a file from your cloud drive. The file is decrypted server-side and streamed. Only non-E2E files are supported. Returns binary file data.

EXAMPLES

RESPONSE

LIST FILES (API)

GET
/apiv1/files
GET
/apiv1/files/{folder_id}

List files and subfolders in a directory. Omit folder_id for the root directory.

EXAMPLES

RESPONSE

CREATE FOLDER (API)

POST
/apiv1/folders

Create a new folder. Sends JSON body with the folder name and optional parent folder ID.

EXAMPLES

RESPONSE

DELETE (API)

DELETE
/apiv1/files/{file_id}
DELETE
/apiv1/folders/{folder_id}

Move a file or folder to trash (soft delete). Trashed items are automatically permanently deleted after 48 hours. Use the trash endpoints to restore or permanently delete sooner.

EXAMPLES

RESPONSE

TRASH (API)

GET
/apiv1/trash
POST
/apiv1/trash/{file_id}/restore
DELETE
/apiv1/trash/{file_id}
DELETE
/apiv1/trash/empty

Manage trashed items. List trash contents, restore files, permanently delete individual files, or empty the entire trash. Trashed items are auto-deleted after 48 hours.

EXAMPLES

RESPONSE (LIST)

ALL ENDPOINTS

Complete reference of all authenticated API endpoints. All require the Authorization: Bearer header and the listed permission.

METHOD ENDPOINT PERMISSION DESCRIPTION
GET /apiv1/keys manage_keys List your active API keys (with permissions & IP whitelist)
POST /apiv1/keys manage_keys Create a new API key (JSON: {"label": "...", "permissions": {...}, "allowed_ips": [...]})
PATCH /apiv1/keys/{key_id} manage_keys Update permissions and/or IP whitelist on an existing key
DELETE /apiv1/keys/{key_id} manage_keys Revoke an API key
POST /apiv1/upload write Upload file(s) to cloud drive
GET /apiv1/download/{file_id} download Download a file (non-E2E only)
GET /apiv1/files read List files in root directory
GET /apiv1/files/{folder_id} read List files in a folder
GET /apiv1/files/{file_id}/properties read Get file details (size, downloads, visibility, etc.)
DELETE /apiv1/files/{file_id} delete Move file to trash
POST /apiv1/folders write Create folder (JSON: {"name": "...", "parent_id": N})
DELETE /apiv1/folders/{folder_id} delete Move folder and contents to trash
GET /apiv1/search?q={query} read Search files and folders by name
GET /apiv1/trash read List trashed items
POST /apiv1/trash/{file_id}/restore restore Restore file from trash
DELETE /apiv1/trash/{file_id} delete Permanently delete from trash
DELETE /apiv1/trash/empty delete Empty entire trash

ERROR CODES

All error responses return an appropriate HTTP status code. JSON endpoints return an error field in the response body.

CODE STATUS DESCRIPTION
400 Bad Request No files provided or invalid request format
401 Unauthorized Login required (e.g. cloud drive upload with is_temp=false)
403 Forbidden Session does not own this file or insufficient permissions
404 Not Found File not found, expired, or invalid token
410 Gone Download limit reached, file has been removed
413 Payload Too Large File exceeds the maximum upload size (5 GB for registered users, 1 GB for guests)
429 Too Many Requests Rate limit exceeded, try again later
507 Insufficient Storage Server disk is full or user storage quota exceeded

EXAMPLE ERROR RESPONSE

RATE LIMITS

API endpoints are rate-limited to prevent abuse. Authenticated users have higher limits than guests. When a rate limit is exceeded, the server returns 429 Too Many Requests.

ENDPOINT GUESTS AUTHENTICATED
/upload 30 / min 1000 / min
/f/{id} 60 / min 2000 / min
/manage/{token} 20 / min 600 / min
/delete/{token} 20 / min 600 / min