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 to store and manage files in your Ubidots account. This service is available from the Industrial license onward and supports file upload, retrieval, and management workflows.

Storage & Security Constraints

To ensure secure and reliable usage, the following limits apply:

Storage Limit: Each Ubidots account includes 50 MB 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. Requests beyond this limit return 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 header. 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

Retrieve 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): The request returns a 404 Not Found response.

---

3. Deleting a file

Delete 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

Retrieve 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 result:

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.