Files and Folders Reference

File and folder CRUD, versioning, copy, move.

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

File object#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "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#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "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:

Required permission: CREATE on target folder / share root.

Errors:

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:

1
2
3
4
5

{
  "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:

1
2
3
4
5
6

{
  "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:

Response:

1
2
3
4
5
6
7
8

{
  "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:

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#

Related#

• Files Guide
• Folders Guide
• Uploads and Downloads
• Versioning and Deduplication