# File Storage API

## 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)**

```bash
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**

```json
{
    "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)**

```bash
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)**

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

**Example Response**

```json
{
    "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)**

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

**Example Response**

```json
{
    "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.                        |