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

# Workspace Files

> List, upload, download, and mutate files in a workspace

Workspace file endpoints use the storage API:

```text theme={null}
https://storage.runtools.ai/v1
```

All paths are workspace-relative. Use `/` for the workspace root.

## Endpoints

| Method   | Path                                | Scope         | Description                                               |
| -------- | ----------------------------------- | ------------- | --------------------------------------------------------- |
| `GET`    | `/v1/workspaces/{id}/files`         | `files:read`  | List root directory                                       |
| `GET`    | `/v1/workspaces/{id}/files/{path}`  | `files:read`  | List a subdirectory                                       |
| `GET`    | `/v1/workspaces/{id}/info`          | `files:read`  | Get organization storage usage for this workspace context |
| `GET`    | `/v1/workspaces/{id}/info/{path}`   | `files:read`  | Get size/count for a file or directory                    |
| `POST`   | `/v1/workspaces/{id}/files`         | `files:write` | Create a file or folder in root                           |
| `POST`   | `/v1/workspaces/{id}/files/{path}`  | `files:write` | Create a file or folder inside a directory                |
| `POST`   | `/v1/workspaces/{id}/upload`        | `files:write` | Upload a multipart file to root or query `id`             |
| `POST`   | `/v1/workspaces/{id}/upload/{path}` | `files:write` | Upload a multipart file to a directory                    |
| `PUT`    | `/v1/workspaces/{id}/files`         | `files:write` | Batch copy or move by file IDs                            |
| `PUT`    | `/v1/workspaces/{id}/files/{path}`  | `files:write` | Rename, copy, or move files                               |
| `DELETE` | `/v1/workspaces/{id}/files`         | `files:write` | Delete files by ID                                        |
| `GET`    | `/v1/workspaces/{id}/direct`        | `files:read`  | Stream one file inline or as a download                   |

`files:*` and `*` also satisfy file scopes.

## List Files

<ParamField path="id" type="string" required>
  Workspace ID.
</ParamField>

<ParamField query="showHidden" type="boolean" default="false">
  Include dotfiles and dot directories.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src?showHidden=false" \
    -H "X-API-Key: $RUNTOOLS_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  [
    {
      "id": "/src/index.ts",
      "value": "index.ts",
      "type": "file",
      "date": "2026-05-06T10:00:00.000Z",
      "size": 842
    },
    {
      "id": "/src/components",
      "value": "components",
      "type": "folder",
      "date": "2026-05-06T10:00:00.000Z",
      "lazy": true,
      "count": 12
    }
  ]
  ```
</ResponseExample>

## Storage Info

Root info returns drive-style storage usage:

```bash theme={null}
curl https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/info \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

```json theme={null}
[
  {
    "free": 10736993952,
    "total": 10737418240,
    "used": 424288
  }
]
```

Path info returns size and entry count:

```bash theme={null}
curl https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/info/src \
  -H "X-API-Key: $RUNTOOLS_API_KEY"
```

```json theme={null}
{
  "Size": 8420,
  "Count": 17
}
```

## Create Files And Folders

<ParamField body="name" type="string" required>
  File or folder name. Names cannot contain path separators.
</ParamField>

<ParamField body="type" type="string" required>
  `file` or `folder`.
</ParamField>

```bash theme={null}
curl -X POST https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "notes",
    "type": "folder"
  }'
```

```json theme={null}
{
  "result": {
    "id": "/src/notes",
    "name": "notes"
  }
}
```

## Upload Files

Uploads use multipart form data. The `file` field is required. The optional `name` field overrides the uploaded filename.

```bash theme={null}
curl -X POST https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/upload/src \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -F "file=@./README.md" \
  -F "name=README.md"
```

```json theme={null}
{
  "id": "/src/README.md",
  "name": "README.md"
}
```

The default upload limit is 100 MB per request.

## Download Files

<ParamField query="id" type="string" required>
  Workspace-relative file ID, such as `/src/README.md`.
</ParamField>

<ParamField query="download" type="boolean" default="false">
  When `true`, return an attachment response. Otherwise, stream inline when possible.
</ParamField>

```bash theme={null}
curl "https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/direct?id=/src/README.md&download=true" \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -o README.md
```

## Rename

```bash theme={null}
curl -X PUT https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files/src/README.md \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "rename",
    "name": "NOTES.md"
  }'
```

## Copy Or Move

Use file IDs from list responses.

```bash theme={null}
curl -X PUT https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "copy",
    "target": "/archive",
    "ids": ["/src/NOTES.md"]
  }'
```

`operation` can be `copy` or `move`. Batch copy and move accept up to 250 IDs.

## Delete

```bash theme={null}
curl -X DELETE https://storage.runtools.ai/v1/workspaces/9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e/files \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["/archive/NOTES.md"]
  }'
```

## Notes

* Personal workspaces are only visible to the owner and organization admins.
* When a workspace is over its storage quota, write operations return an error until usage is reduced or the org limit is updated.
* Directory listing hides dotfiles unless `showHidden=true`.