---
title: "Local File Storage | DreamFactory Docs"
source: "https://docs.dreamfactory.com/api-generation-and-connections/api-types/file-services/local-file-storage"
canonical_url: "https://docs.dreamfactory.com/api-generation-and-connections/api-types/file-services/local-file-storage"
converted_at: "2026-04-22T14:38:56.607Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
DreamFactory's Local File Storage connector provides REST API access to files stored directly on the DreamFactory server's filesystem. This is ideal for development, testing, and scenarios where cloud storage is not required.

---

## Use Cases[​](#use-cases)

- **Development and testing**: Quick setup without external dependencies

- **Application assets**: Store images, documents, and static files

- **Temporary file processing**: Upload files for server-side processing

- **Small-scale deployments**: When cloud storage is unnecessary overhead

- **Air-gapped environments**: No internet connectivity required

Production ConsiderationsFor production deployments, consider cloud storage (S3, Azure Blob) for:

- Horizontal scaling (multiple DreamFactory instances)

- Backup and disaster recovery

- CDN integration

- Larger storage capacity

---

## Creating a Local File Storage Service[​](#creating-a-local-file-storage-service)

### Step 1: Navigate to API Generation[​](#step-1-navigate-to-api-generation)

Log in to your DreamFactory instance using an administrator account and select the **API Generation & Connections** tab. Set your API Type to **File**.

### Step 2: Create New Service[​](#step-2-create-new-service)

Click the purple plus button to create a new file service, then search for and select **Local File Storage**.

### Step 3: Configure Service Details[​](#step-3-configure-service-details)

FieldDescriptionExampleNameService name (lowercase, alphanumeric, used in API URL)`files`LabelDisplay name in admin console`Local Files`DescriptionService description`Local file storage for application assets`

### Step 4: Configure Storage Path[​](#step-4-configure-storage-path)

In the **Config** section, specify the root folder path:

FieldDescriptionExampleRoot FolderAbsolute path on the server`/var/www/storage/files`

PermissionsEnsure the web server user (e.g., `www-data`, `nginx`) has read/write permissions on the specified root folder:

```
sudo mkdir -p /var/www/storage/filessudo chown -R www-data:www-data /var/www/storage/filessudo chmod -R 755 /var/www/storage/files
```

### Step 5: Save and Test[​](#step-5-save-and-test)

Click **Save** to create the service. Navigate to **API Docs** to view the generated endpoints and test operations.

---

## Configuration Options[​](#configuration-options)

FieldTypeRequiredDefaultDescription`root_folder`stringYes-Absolute path to the storage directory`public_path`stringNo-Public URL path if files are web-accessible`is_public`booleanNofalseAllow unauthenticated file downloads

### Advanced Options[​](#advanced-options)

FieldTypeDefaultDescription`cache_enabled`booleanfalseEnable response caching`cache_ttl`integer0Cache time-to-live in seconds`allow_upsert`booleantrueAllow PUT to create new files

---

## API Endpoints[​](#api-endpoints)

Once configured, DreamFactory generates these endpoints:

MethodEndpointDescription`GET``/api/v2/{service_name}/`List root directory`GET``/api/v2/{service_name}/{path}/`List folder contents`GET``/api/v2/{service_name}/{path}`Download file`POST``/api/v2/{service_name}/`Create folder or upload file`POST``/api/v2/{service_name}/{path}/`Create subfolder or upload file`PUT``/api/v2/{service_name}/{path}`Replace file contents`PATCH``/api/v2/{service_name}/{path}`Update file properties`DELETE``/api/v2/{service_name}/{path}`Delete file or folder

---

## API Examples[​](#api-examples)

### List Directory Contents[​](#list-directory-contents)

```
curl -X GET "https://example.com/api/v2/files/" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY"
```

**Response:**

```
{  "resource": [    {      "path": "images/",      "type": "folder",      "name": "images",      "last_modified": "2026-02-10T14:30:00Z"    },    {      "path": "config.json",      "type": "file",      "name": "config.json",      "content_type": "application/json",      "content_length": 2048,      "last_modified": "2026-02-09T10:15:00Z"    }  ]}
```

### Create a Folder[​](#create-a-folder)

```
curl -X POST "https://example.com/api/v2/files/" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \  -H "X-Folder-Name: documents"
```

**Response:**

```
{  "name": "documents",  "path": "documents/"}
```

### Upload a File[​](#upload-a-file)

Using the file path in the URL:

```
curl -X POST "https://example.com/api/v2/files/documents/report.pdf" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \  -H "Content-Type: application/pdf" \  --data-binary @report.pdf
```

Using the `X-File-Name` header:

```
curl -X POST "https://example.com/api/v2/files/documents/" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \  -H "X-File-Name: report.pdf" \  -H "Content-Type: application/pdf" \  --data-binary @report.pdf
```

**Response:**

```
{  "name": "report.pdf",  "path": "documents/report.pdf",  "content_type": "application/pdf",  "content_length": 102400}
```

### Download a File[​](#download-a-file)

```
curl -X GET "https://example.com/api/v2/files/documents/report.pdf" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY" \  -o report.pdf
```

### Get File Properties[​](#get-file-properties)

Add `?include_properties=true` to get metadata without downloading:

```
curl -X GET "https://example.com/api/v2/files/documents/report.pdf?include_properties=true" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY"
```

**Response:**

```
{  "path": "documents/report.pdf",  "name": "report.pdf",  "type": "file",  "content_type": "application/pdf",  "content_length": 102400,  "last_modified": "2026-02-10T15:45:00Z"}
```

### Delete a File[​](#delete-a-file)

```
curl -X DELETE "https://example.com/api/v2/files/documents/old-report.pdf" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY"
```

### Delete a Folder[​](#delete-a-folder)

Add `?force=true` to delete non-empty folders:

```
curl -X DELETE "https://example.com/api/v2/files/old-documents/?force=true" \  -H "X-DreamFactory-API-Key: YOUR_API_KEY"
```

---

## File Upload Limits[​](#file-upload-limits)

Upload size limits are controlled by your web server and PHP configuration, not DreamFactory.

### Nginx Configuration[​](#nginx-configuration)

Add to your `nginx.conf` or site configuration:

```
client_max_body_size 100M;
```

### PHP Configuration[​](#php-configuration)

Modify `php.ini`:

```
upload_max_filesize = 100Mpost_max_size = 105M
```

Restart your web server and PHP-FPM after making changes.

---

## Common Errors[​](#common-errors)

Error CodeMessageCauseSolution400Invalid pathPath contains invalid charactersUse alphanumeric characters, dashes, underscores403ForbiddenPermission denied on filesystemCheck folder permissions for web server user404Not FoundFile or folder does not existVerify the path exists on the server409ConflictFile already existsUse PUT to overwrite or delete first413Payload Too LargeFile exceeds upload limitIncrease server upload limits500Internal Server ErrorServer-side errorCheck DreamFactory logs for details

### Troubleshooting Permissions[​](#troubleshooting-permissions)

If you receive 403 errors, verify filesystem permissions:

```
# Check current permissionsls -la /var/www/storage/files# Fix ownershipsudo chown -R www-data:www-data /var/www/storage/files# Fix permissions (directories need execute bit)sudo find /var/www/storage/files -type d -exec chmod 755 {} \;sudo find /var/www/storage/files -type f -exec chmod 644 {} \;
```

---

## Security Considerations[​](#security-considerations)

### Path Traversal Protection[​](#path-traversal-protection)

DreamFactory sanitizes paths to prevent directory traversal attacks. Requests containing `../` or absolute paths outside the root folder are rejected.

### Role-Based Access Control[​](#role-based-access-control)

Configure RBAC to restrict file operations:

1. Navigate to **Roles** in the admin console

2. Select or create a role

3. Under **Access**, add the file service

4. Configure allowed paths and operations:

- **GET** for read-only access

- **POST** for upload-only

- **DELETE** to allow deletions

Example: Allow uploads to `/uploads/` but not access to `/config/`:

PathMethods`uploads/*`GET, POST`public/*`GET

---

## Next Steps[​](#next-steps)

- **[AWS S3](/api-generation-and-connections/api-types/file-services/aws-s3)**: Migrate to cloud storage for production

- **[File Services Overview](/api-generation-and-connections/api-types/file-services/file-services-overview)**: Compare all file storage options

- **[Role-Based Access Control](/api-security/rbac)**: Configure fine-grained permissions