File Storage API

The Ubidots File Storage API enables account owners to securely upload, retrieve, manage, and delete files within Ubifunctions.

Overview

The Ubidots File Storage API provides a secure and efficient way for users to store and manage files within their Ubidots accounts. This service is available from the Industrial license onwards and is designed to offer seamless integration for file storage, retrieval, and management.

Storage & Security Constraints

To ensure optimal usage and security, the following limitations apply:

Storage Limit: Each Ubidots account is allocated 50MB of storage.

Restricted File Extensions: To enhance security, potentially malicious file types are blocked. The following extensions are not allowed:

.js, .exe, .sh, .php, .bat, .cmd, .msi, .vbs, and other executable/script files.

Request Rate Limit

The API enforces a maximum of 5 requests per second per client IP to ensure fair usage and system stability. Excessive requests beyond this limit will result in a 429 Too Many Requests response.

Filename Rules: Only the following characters are allowed in filenames:

• Letters (a-z, A-Z)

• Numbers (0-9)

• Underscores (_), dashes (-), and dots (.)

Token Authentication: All API requests must include an X-Auth-Token in the header for authentication. Only account-level tokens are accepted (organization and device tokens are rejected).

Supported API Operations

1️Uploading a File

Upload a file to your Ubidots storage.

API Endpoint:

POST https://files.api.ubidots.com/files/{username}/{filename}

Example Request (cURL)

curl -X POST "https://files.api.ubidots.com/files/yourusername/file.txt" \
     -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
     -F "file=@path/to/your/file.txt"

Example Response

{
    "message": "File uploaded successfully",
    "filename": "file.txt",
    "username": "yourusername",
    "used_storage_mb": "10.5"
}

---

2️Downloading a File

Retrieves a file from your Ubidots storage.

API Endpoint:

GET https://files.api.ubidots.com/files/{username}/{filename}

Example Request (cURL)

curl -X GET "https://files.api.ubidots.com/files/yourusername/testfile1.txt" \
     -H "X-Auth-Token: YOUR_AUTH_TOKEN" \
     -o fileDownloaded.txt

Response:

✅ If successful (200 OK): The file is downloaded. ❌ If the file does not exist (404 Not Found):

---

3️Deleting a File

Removes a file from your storage.

API Endpoint:

DELETE https://files.api.ubidots.com/files/{username}/{filename}

Example Request (cURL)

curl -X DELETE "https://files.api.ubidots.com/files/yourusername/test1.txt" \
     -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Example Response

{
    "message": "File 'test1.txt' deleted successfully"
}

---

4️Listing All Files

Retrieves a list of all stored files and current storage usage.

API Endpoint:

GET https://files.api.ubidots.com/files/{username}

Example Request (cURL)

curl -X GET "https://files.api.ubidots.com/files/yourusername" \
     -H "X-Auth-Token: YOUR_AUTH_TOKEN"

Example Response

{
    "username": "yourusername",
    "total_files": 2,
    "used_storage_mb": 18.42,
    "remaining_storage_mb": 31.58,
    "files": [
        {"filename": "test1.txt", "size_mb": 8.42},
        {"filename": "backup.zip", "size_mb": 10.0}
    ]
}

API Response Codes

Each API operation returns specific HTTP status codes based on the request outcome:

Status Code	Description
200 OK	Request was successful (file uploaded, downloaded, listed, or deleted).
400 Bad Request	The request contained invalid parameters, such as an incorrect filename.
401 Unauthorized	The provided X-Auth-Token is missing or invalid.
403 Forbidden	The user is not authorized to access this resource (wrong username or insufficient permissions).
404 Not Found	The requested file does not exist in the storage.
413 Payload Too Large	The file exceeds the maximum storage limit of 50MB.
415 Unsupported Media Type	The file has a restricted extension and cannot be uploaded.
429 Too Many Requests	Exceeded the limit of 5 requests per second from the same client IP or token.
500 Internal Server Error	An unexpected error occurred on the server (e.g., S3 failure or token validation issue).
503 Service Unavailable	The authentication service or storage backend is temporarily unreachable.