> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instapods.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Browse, read, write, upload, and manage files inside pods.

All file endpoints operate within the pod's filesystem. Paths must be absolute and within `/home/instapod`, `/var/www`, or `/tmp`.

## List Files

```
GET /api/pods/{name}/files?path=/home/instapod/app
```

| Query Param | Type   | Default        | Description       |
| ----------- | ------ | -------------- | ----------------- |
| `path`      | string | Pod's app root | Directory to list |

**Response: `200 OK`**

```json theme={null}
{
  "path": "/home/instapod/app",
  "files": [
    {
      "name": "index.js",
      "permissions": "-rw-r--r--",
      "size": "1234",
      "is_dir": false
    },
    {
      "name": "node_modules",
      "permissions": "drwxr-xr-x",
      "size": "4096",
      "is_dir": true
    }
  ]
}
```

Returns an empty `files` array if the directory doesn't exist.

## Read a File

```
GET /api/pods/{name}/files/content?path=/home/instapod/app/index.js
```

| Query Param | Type   | Required | Description        |
| ----------- | ------ | -------- | ------------------ |
| `path`      | string | Yes      | Absolute file path |

**Response: `200 OK`**

```json theme={null}
{
  "path": "/home/instapod/app/index.js",
  "content": "const express = require('express');\n..."
}
```

## Write a File

```
PUT /api/pods/{name}/files/content
```

**Request Body:**

```json theme={null}
{
  "path": "/home/instapod/app/index.js",
  "content": "const express = require('express');\n..."
}
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "saved",
  "path": "/home/instapod/app/index.js"
}
```

Parent directories are created automatically if they don't exist.

## Upload a File

```
POST /api/pods/{name}/files/upload
```

**Request:** `multipart/form-data`

| Field  | Type   | Required | Description                          |
| ------ | ------ | -------- | ------------------------------------ |
| `file` | File   | Yes      | File to upload (max 32 MB)           |
| `path` | string | No       | Target directory (default: app root) |

**Response: `200 OK`**

```json theme={null}
{
  "status": "uploaded",
  "path": "/home/instapod/app/style.css"
}
```

## Download a File

```
GET /api/pods/{name}/files/download?path=/home/instapod/app/data.json
```

Returns the raw file contents as binary with `Content-Disposition: attachment`.

## Delete a File

```
DELETE /api/pods/{name}/files?path=/home/instapod/app/old-file.js
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "deleted",
  "path": "/home/instapod/app/old-file.js"
}
```

Works on both files and directories (recursive delete).

## Rename / Move

```
POST /api/pods/{name}/files/rename
```

**Request Body:**

```json theme={null}
{
  "old_path": "/home/instapod/app/old-name.js",
  "new_path": "/home/instapod/app/new-name.js"
}
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "renamed",
  "old_path": "/home/instapod/app/old-name.js",
  "new_path": "/home/instapod/app/new-name.js"
}
```

## Copy

```
POST /api/pods/{name}/files/copy
```

**Request Body:**

```json theme={null}
{
  "source_path": "/home/instapod/app/config.js",
  "dest_path": "/home/instapod/app/config.backup.js"
}
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "copied",
  "source_path": "/home/instapod/app/config.js",
  "dest_path": "/home/instapod/app/config.backup.js"
}
```

Works recursively for directories.

## Create Folder

```
POST /api/pods/{name}/folders
```

**Request Body:**

```json theme={null}
{
  "path": "/home/instapod/app/src/components"
}
```

**Response: `200 OK`**

```json theme={null}
{
  "status": "created",
  "path": "/home/instapod/app/src/components"
}
```

Creates the full directory tree (equivalent to `mkdir -p`).

***

## Path Validation

All paths must be:

* **Absolute** (start with `/`)
* **Within allowed directories**: `/home/instapod`, `/var/www`, or `/tmp`
* **Free of traversal** (no `..` segments)

Invalid paths return `400 Bad Request`.