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

# Files

> Browse and manage the file tree within a space. Upload files, create folders, and link deliverables to tasks.

Each space has a hierarchical file tree. Nodes are either **files** or **folders**. The REST endpoints below cover tree navigation, metadata management, and file creation. Real-time collaborative editing uses a separate WebSocket connection documented at the bottom of this page.

## List file nodes

```
GET /api/v1/organizations/{orgId}/spaces/{spaceId}/files
```

Returns the immediate children of a folder (or the space root), optionally filtered by name. Pass `scope=space` with `q` to search across the entire space.

**Path parameters**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>

**Query parameters**

<ParamField query="parentId" type="string">
  UUID of a folder node. Omit to list the space root.
</ParamField>

<ParamField query="q" type="string">
  Name filter (case-insensitive substring match).
</ParamField>

<ParamField query="scope" type="string">
  Set to `"space"` together with `q` to search the entire space tree instead of just the current folder.
</ParamField>

**Example** — list the root

```bash theme={null}
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Example** — search across the whole space

```bash theme={null}
curl "https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files?q=report&scope=space" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{
  "nodes": [
    {
      "id": "018e1234-abcd-7000-8000-000000000070",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "parent_id": null,
      "kind": "folder",
      "name": "Deliverables",
      "mime_type": null,
      "size_bytes": null,
      "checksum_sha256": null,
      "created_by": "018e1234-abcd-7000-8000-000000000050",
      "created_at": "2024-03-15T09:00:00Z",
      "updated_at": "2024-03-15T09:00:00Z",
      "deleted_at": null
    },
    {
      "id": "018e1234-abcd-7000-8000-000000000072",
      "space_id": "018e1234-abcd-7000-8000-000000000002",
      "parent_id": null,
      "kind": "file",
      "name": "roadmap.md",
      "mime_type": "text/markdown",
      "size_bytes": 4096,
      "checksum_sha256": "e3b0c44298fc1c149afb",
      "created_by": "018e1234-abcd-7000-8000-000000000050",
      "created_at": "2024-03-15T09:30:00Z",
      "updated_at": "2024-03-18T14:00:00Z",
      "deleted_at": null
    }
  ]
}
```

<ResponseField name="nodes[].id" type="string">Node UUID.</ResponseField>
<ResponseField name="nodes[].space_id" type="string">Parent space UUID.</ResponseField>
<ResponseField name="nodes[].parent_id" type="string">UUID of the parent folder, or `null` for root-level nodes.</ResponseField>
<ResponseField name="nodes[].kind" type="string">`"file"` or `"folder"`.</ResponseField>
<ResponseField name="nodes[].name" type="string">File or folder name.</ResponseField>
<ResponseField name="nodes[].mime_type" type="string">MIME type (files only), or `null`.</ResponseField>
<ResponseField name="nodes[].size_bytes" type="integer">File size in bytes (files only), or `null`.</ResponseField>
<ResponseField name="nodes[].checksum_sha256" type="string">SHA-256 hex checksum of file content (files only), or `null`.</ResponseField>
<ResponseField name="nodes[].created_by" type="string">UUID of the user who created this node.</ResponseField>
<ResponseField name="nodes[].deleted_at" type="string">Populated when the node has been deleted, otherwise `null`.</ResponseField>

***

## Get the full tree

```
GET /api/v1/organizations/{orgId}/spaces/{spaceId}/files/tree
```

Returns all non-deleted nodes in the space in a flat list. Suitable for building a client-side tree.

**Example**

```bash theme={null}
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files/tree \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{ "nodes": [ ... ] }
```

Same node shape as the list response above.

***

## Get a file node

```
GET /api/v1/organizations/{orgId}/spaces/{spaceId}/files/{nodeId}
```

Returns a single node's metadata.

**Path parameters**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="nodeId" type="string" required>Node UUID.</ParamField>

**Example**

```bash theme={null}
curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files/YOUR_NODE_ID \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Response** `200 OK`

```json theme={null}
{ "node": { ... } }
```

***

## Create a folder

```
POST /api/v1/organizations/{orgId}/spaces/{spaceId}/files/folders
```

Creates a new folder node. Requires the `files.write` permission.

**Request body**

<ParamField body="name" type="string" required>
  Folder name. Leading/trailing whitespace is stripped.
</ParamField>

<ParamField body="parent_id" type="string">
  UUID of the parent folder. Omit or set to `null` to create at the space root.
</ParamField>

**Example**

```bash theme={null}
curl -X POST \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files/folders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reports", "parent_id": null}'
```

**Response** `201 Created`

```json theme={null}
{
  "node": {
    "id": "018e1234-abcd-7000-8000-000000000075",
    "space_id": "018e1234-abcd-7000-8000-000000000002",
    "parent_id": null,
    "kind": "folder",
    "name": "Reports",
    "created_by": "018e1234-abcd-7000-8000-000000000050",
    "created_at": "2024-03-20T11:00:00Z",
    "updated_at": "2024-03-20T11:00:00Z",
    "deleted_at": null
  }
}
```

***

## Rename or move a node

```
PATCH /api/v1/organizations/{orgId}/spaces/{spaceId}/files/{nodeId}
```

Renames and/or moves a file or folder. Requires the `files.write` permission. Both fields are optional; supply at least one.

**Path parameters**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="nodeId" type="string" required>Node UUID.</ParamField>

**Request body**

<ParamField body="name" type="string">
  New name. Cannot be empty if provided.
</ParamField>

<ParamField body="parent_id" type="string">
  New parent folder UUID. Pass `null` to move to the space root. Omit entirely to leave the parent unchanged.
</ParamField>

**Example** — rename

```bash theme={null}
curl -X PATCH \
  https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files/YOUR_NODE_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q2 Reports"}'
```

**Response** `200 OK`

Returns the updated node object wrapped in `{"node": {...}}`.

***

## Delete a file node

```
DELETE /api/v1/organizations/{orgId}/spaces/{spaceId}/files/{nodeId}
```

Soft-deletes the node (sets `deleted_at`). Requires the `files.write` permission.

**Path parameters**

<ParamField path="orgId" type="string" required>Organization UUID.</ParamField>
<ParamField path="spaceId" type="string" required>Space UUID.</ParamField>
<ParamField path="nodeId" type="string" required>Node UUID.</ParamField>

**Response** `204 No Content`

***

## Collaborative editing

Real-time collaborative document editing uses a WebSocket connection at:

```
wss://your-hostname/api/v1/organizations/{orgId}/spaces/{spaceId}/files/collab/ws
```

The REST endpoints above manage the file tree structure and metadata. Document content is synchronized over the WebSocket using the Yjs CRDT protocol. Authenticate the WebSocket upgrade by passing your token as a query parameter: `?token=YOUR_TOKEN`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.