---
title: Files and Folders Reference
path: reference/files-and-folders
status: published
---

File and folder CRUD, versioning, copy, move.

**Base paths:** `/api/v1/files/`, `/api/v1/folders/`

## File object

```json
{
  "id": "fil_01J3K",
  "tenant_id": "tnt_01J3A",
  "share_id": "shr_01J3H",
  "folder_id": "fld_01J3I",
  "name": "spec.pdf",
  "path": "/Engineering/spec.pdf",
  "mime_type": "application/pdf",
  "size": 48293,
  "checksum_sha256": "a9f2...",
  "version": 4,
  "owner_id": "usr_01J3N",
  "created_by": "usr_01J3N",
  "created_at": "2026-04-20T10:00:00Z",
  "modified_by": "usr_01J3N",
  "modified_at": "2026-04-23T10:15:00Z",
  "is_deleted": false,
  "vectorized_at": "2026-04-20T10:05:12Z"
}
```

## Folder object

```json
{
  "id": "fld_01J3I",
  "tenant_id": "tnt_01J3A",
  "share_id": "shr_01J3H",
  "parent_id": null,
  "name": "Engineering",
  "path": "/Engineering",
  "owner_id": "usr_01J3N",
  "created_by": "usr_01J3N",
  "created_at": "2026-01-15T08:00:00Z",
  "modified_at": "2026-04-22T14:30:00Z",
  "is_deleted": false
}
```

## Files

### GET /api/v1/files/{file_id}

File metadata.

**Required permission:** `READ`.

### GET /api/v1/files/{file_id}/content

Stream file content.

**Query:** `version` — download a specific version.

**Headers supported:**
- `Range: bytes=start-end` — partial content, returns 206.

**Response headers:**
- `Content-Length`
- `Content-Disposition: attachment; filename="..."`
- `Accept-Ranges: bytes`

**Required permission:** `READ`.

### POST /api/v1/files

Upload a new file (multipart). Returns 201.

**Form fields:**

| Field | Required | Notes |
|-------|----------|-------|
| `share_id` | Yes | Destination share |
| `folder_id` | No | Destination folder; omit for root |
| `name` | No | Override filename |
| `file` | Yes | File content |

**Required permission:** `CREATE` on target folder / share root.

**Errors:**

| Code | When |
|------|------|
| `NAME_CONFLICT` | Sibling with same name exists |
| `PAYLOAD_TOO_LARGE` | Exceeds tenant max file size |
| `QUOTA_EXCEEDED` | Any applicable quota exceeded |

### PATCH /api/v1/files/{file_id}

Rename or update metadata.

**Body:** `name`.

**Required permission:** `WRITE`.

### DELETE /api/v1/files/{file_id}

Delete file.

**Query:** `permanent` (default false).

**Required permission:** `DELETE`.

### POST /api/v1/files/{file_id}/copy

Copy to another location. Returns 201.

**Body:**

```json
{
  "target_folder_id": "fld_01J4A",
  "target_share_id": "shr_01J4Z",
  "new_name": "copy.pdf"
}
```

Exactly one of `target_folder_id` or `target_share_id` must be set.

**Required permission:** `READ` on source, `CREATE` on target.

### POST /api/v1/files/{file_id}/move

Move to another location.

**Body:** `target_folder_id` or `target_share_id`.

**Required permission:** `DELETE` on source, `CREATE` on target.

### GET /api/v1/files/{file_id}/versions

List version history.

**Required permission:** `READ`.

**Response:**

```json
{
  "versions": [
    {"id": "ver_01J4Q", "version_number": 4, "size": 48293, "checksum_sha256": "a9f2...", "created_by": "usr_01J3N", "created_at": "2026-04-23T10:15:00Z", "comment": null}
  ],
  "total": 4
}
```

### POST /api/v1/files/{file_id}/versions/{version}/restore

Restore a previous version (creates a new version with that content).

**Required permission:** `WRITE`.

**Response:** `{id, restored_version, new_version_id}`.

## Folders

### GET /api/v1/folders/{folder_id}

Folder metadata. Use the special ID `root` to address the share root.

**Required permission:** `READ`.

### GET /api/v1/folders/{folder_id}/children

List folder contents.

**Query:**

| Param | Notes |
|-------|-------|
| `share_id` | Required |
| `include_deleted` | Default false |

**Response:**

```json
{
  "items": [
    {"id": "fld_01J3J", "name": "Specs", "type": "folder"},
    {"id": "fil_01J3K", "name": "spec.pdf", "type": "file", "size": 48293, "mime_type": "application/pdf", "modified_at": "2026-04-23T10:15:00Z"}
  ],
  "path": "/Engineering",
  "total": 2
}
```

**Required permission:** `READ`.

### POST /api/v1/folders

Create folder. Returns 201.

**Body:**

| Field | Required | Notes |
|-------|----------|-------|
| `share_id` | Yes | |
| `name` | Yes | |
| `parent_id` | No | Omit for root |

**Required permission:** `CREATE` on parent (or share).

### PATCH /api/v1/folders/{folder_id}

Rename.

**Body:** `name`.

**Required permission:** `WRITE`.

### DELETE /api/v1/folders/{folder_id}

Delete recursively.

**Query:** `permanent`.

**Required permission:** `DELETE` on folder and all descendants.

### POST /api/v1/folders/{folder_id}/move

Move folder.

**Body:** `target_parent_id` or `target_share_id`.

**Required permission:** `DELETE` on source, `CREATE` on target.

## Error codes common to both

| Code | HTTP | When |
|------|------|------|
| `NOT_FOUND` | 404 | Doesn't exist or not visible |
| `NAME_CONFLICT` | 409 | Sibling name collision |
| `INVALID_PATH` | 400 | Invalid name characters |
| `RESOURCE_DELETED` | 410 | Soft-deleted |
| `AUTHZ_PERMISSION_DENIED` | 403 | Missing permission |
| `PAYLOAD_TOO_LARGE` | 413 | File size limit |
| `QUOTA_EXCEEDED` | 507 | Any applicable quota |

## Related

- [Files Guide](/docs/scaidrive/api-guides/files)
- [Folders Guide](/docs/scaidrive/api-guides/folders)
- [Uploads and Downloads](/docs/scaidrive/api-guides/uploads-and-downloads)
- [Versioning and Deduplication](/docs/scaidrive/core-concepts/versioning-and-deduplication)