Upload.am API Documentation

1. User Login (POST /auth/login)

Authenticates a user and returns a JWT token and refresh token.

Authentication: None

Content-Type: application/x-www-form-urlencoded

Parameters

Parameter	Type	Required	Description
login	String	Yes	User login (username, not email, e.g., example_user)
password	String	Yes	User password

Example Request

curl -X POST https://upload.am/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "login=example_user&password=example_password"

Example Response

{
  "success": true,
  "data": {
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "a1b2c3d4e5f6..."
  }
}

Example Error Response

{
  "success": false,
  "error": "Invalid login or password"
}

2. Refresh Token (POST /auth/refresh)

Refreshes an expired JWT token using a refresh token.

Authentication: None

Content-Type: application/x-www-form-urlencoded

Parameters

Parameter	Type	Required	Description
refresh_token	String	Yes	Refresh token from /auth/login

Example Request

curl -X POST https://upload.am/api/v1/auth/refresh \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=a1b2c3d4e5f6..."

Example Response

{
  "success": true,
  "data": {
    "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "refreshToken": "new_refresh_token..."
  }
}

Example Error Response

{
  "success": false,
  "error": "Invalid or expired refresh token"
}

3. Precheck File Upload (POST /precheck)

Validates file metadata before upload, returning a fileId. Checks file type, size (max 2GB), and storage limits.

Authentication: Optional (JWT)

Content-Type: application/x-www-form-urlencoded

Parameters

Parameter	Type	Required	Description
fileName	String	Yes	File name (e.g., photo.jpg)
fileSize	Integer	Yes	File size in bytes (max 2GB)

Supported File Types

jpg, jpeg, png, gif, bmp, pdf, doc, docx, txt, zip, rar, 7z, tar, gz, bz2, xlsx, ppt, pptx, odt, ods, odp, mp3, mp4, avi, mkv, wav, mov, webm

Example Request

curl -X POST https://upload.am/api/v1/precheck \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "fileName=photo.jpg&fileSize=1048576" \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true,
  "data": {
    "fileId": "temp_68586xxxxxx"
  }
}

Example Error Response

{
  "success": false,
  "error": "This file type is not allowed."
}

4. Upload File (POST /upload)

Uploads one or more files to S3 storage with validation. Files expire after 30 days for non-premium users (plan_id <= 1) or have no expiration for premium users (plan_id > 1).

Authentication: Optional (JWT)

Content-Type: multipart/form-data

Parameters

Parameter	Type	Required	Description
file	File	Yes	File(s) to upload
fileId	String	Yes	fileId from /precheck
password	String	No	Download password
folder_id	Integer	No	Folder ID to store the file

Supported File Types

jpg, jpeg, png, gif, bmp, pdf, doc, docx, txt, zip, rar, 7z, tar, gz, bz2, xlsx, ppt, pptx, odt, ods, odp, mp3, mp4, avi, mkv, wav, mov, webm

Example Request (Single File)

curl -X POST https://upload.am/api/v1/upload \
  -F "file=@photo.jpg" \
  -F "fileId=temp_68586xxxxxx" \
  -F "password=secure123" \
  -F "folder_id=1" \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response (Single File)

[{
  "success": true,
  "data": {
    "fileName": "photo.jpg",
    "fileSize": "218.94 KB",
    "fileLink": "https://upload.am/download.php?file=68586xxxxxx.jpg",
    "directUrl": "https://upload.de-fra.i3storage.com/2025/07/03/68586xxxxxx.jpg?...",
    "uploadDate": "2025-07-03 00:00:00",
    "expiresAt": "2025-08-02 00:00:00",
    "folderId": 1
  }
}]

Example Request (Multiple Files)

curl -X POST https://upload.am/api/v1/upload \
  -F "file=@photo.jpg" \
  -F "fileId=temp_68586xxxxxx" \
  -F "file=@document.pdf" \
  -F "fileId=temp_68587xxxxxx" \
  -F "password=secure123" \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response (Multiple Files)

[{
  "success": true,
  "data": {
    "fileName": "photo.jpg",
    "fileSize": "218.94 KB",
    "fileLink": "https://upload.am/download.php?file=68586xxxxxx.jpg",
    "directUrl": "https://upload.de-fra.i3storage.com/2025/07/03/68586xxxxxx.jpg?...",
    "uploadDate": "2025-07-03 00:00:00",
    "expiresAt": "2025-08-02 00:00:00",
    "folderId": null
  }
}, {
  "success": true,
  "data": {
    "fileName": "document.pdf",
    "fileSize": "1.5 MB",
    "fileLink": "https://upload.am/download.php?file=68587xxxxxx.pdf",
    "directUrl": "https://upload.de-fra.i3storage.com/2025/07/03/68587xxxxxx.pdf?...",
    "uploadDate": "2025-07-03 00:00:00",
    "expiresAt": "2025-08-02 00:00:00",
    "folderId": null
  }
}]

Example Error Response

[{
  "success": false,
  "error": "Invalid file type."
}]

5. Download File (GET /download)

Returns a presigned S3 URL for downloading a file. JWT is optional but used for logging downloads if provided.

Authentication: None

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
file	String	Yes	File key (e.g., 68586xxxxxx.jpg)
password	String	No	Download password (required if set during upload)

Example Request

curl -X GET "https://upload.am/api/v1/download?file=68586xxxxxx.jpg&password=secure123" \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true,
  "data": {
    "presignedUrl": "https://upload.de-fra.i3storage.com/2025/07/03/68586xxxxxx.jpg?...",
    "fileName": "68586xxxxxx.jpg",
    "fileSize": "218.94 KB",
    "expiresAt": "2025-08-02 00:00:00"
  }
}

Example Error Response

{
  "success": false,
  "error": "Invalid password"
}

6. List User Files (GET /files)

Lists files uploaded by the authenticated user.

Authentication: Required (JWT)

Content-Type: application/json

Example Request

curl -X GET https://upload.am/api/v1/files \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true,
  "data": [{
    "id": 123,
    "fileName": "68586xxxxxx.jpg",
    "fileLink": "https://upload.am/download.php?file=68586xxxxxx.jpg",
    "uploadDate": "2025-07-03",
    "expiresAt": "2025-08-02 00:00:00",
    "fileSize": "218.94 KB"
  }]
}

Example Error Response

{
  "success": false,
  "error": "Authorization header missing"
}

7. Delete File (DELETE /file/{id})

Deletes a file by ID.

Authentication: Required (JWT)

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
id	Integer	Yes	File ID

Example Request

curl -X DELETE https://upload.am/api/v1/file/123 \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true
}

Example Error Response

{
  "success": false,
  "error": "File not found or access denied"
}

8. Create Folder (POST /folder)

Creates a new folder for the authenticated user.

Authentication: Required (JWT)

Content-Type: application/x-www-form-urlencoded

Parameters

Parameter	Type	Required	Description
folder_name	String	Yes	Name of the folder (max 255 characters)

Example Request

curl -X POST https://upload.am/api/v1/folder \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "folder_name=MyFolder" \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true,
  "data": {
    "folder_id": 1,
    "folder_name": "MyFolder"
  }
}

Example Error Response

{
  "success": false,
  "error": "Invalid folder name"
}

9. Delete Folder (DELETE /folder/{id})

Deletes a folder by ID and moves its files to the root.

Authentication: Required (JWT)

Content-Type: application/json

Parameters

Parameter	Type	Required	Description
id	Integer	Yes	Folder ID

Example Request

curl -X DELETE https://upload.am/api/v1/folder/1 \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true
}

Example Error Response

{
  "success": false,
  "error": "Folder not found or access denied"
}

10. Get Storage Usage (GET /storage)

Returns the authenticated user's storage usage and limit.

Authentication: Required (JWT)

Content-Type: application/json

Example Request

curl -X GET https://upload.am/api/v1/storage \
  -H "Authorization: Bearer <your_jwt_token>"

Example Response

{
  "success": true,
  "data": {
    "usedStorage": 5.23,
    "storageLimit": 25.00,
    "usedPercent": 20.92
  }
}

Example Error Response

{
  "success": false,
  "error": "Authorization header missing"
}