# File Storage API

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

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

Retrieve 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):** 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)**

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

Retrieve 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 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.                        |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ubidots.com/ubifunctions/storage/file-storage-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.