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

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

Query parameters

parentId · string

UUID of a folder node. Omit to list the space root.

q · string

Name filter (case-insensitive substring match).

scope · string

Set to "space" together with q to search the entire space tree instead of just the current folder.

Example — list the root

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

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

{
  "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
    }
  ]
}

nodes[].id · string

Node UUID.

nodes[].space_id · string

Parent space UUID.

nodes[].parent_id · string

UUID of the parent folder, or null for root-level nodes.

nodes[].kind · string

"file" or "folder".

nodes[].name · string

File or folder name.

nodes[].mime_type · string

MIME type (files only), or null.

nodes[].size_bytes · integer

File size in bytes (files only), or null.

nodes[].checksum_sha256 · string

SHA-256 hex checksum of file content (files only), or null.

nodes[].created_by · string

UUID of the user who created this node.

nodes[].deleted_at · string

Populated when the node has been deleted, otherwise null.

---

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

curl https://your-hostname/api/v1/organizations/YOUR_ORG_ID/spaces/YOUR_SPACE_ID/files/tree \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200 OK

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

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

nodeId · string · required

Node UUID.

Example

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

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

name · string · required

Folder name. Leading/trailing whitespace is stripped.

parent_id · string

UUID of the parent folder. Omit or set to null to create at the space root.

Example

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

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

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

nodeId · string · required

Node UUID.

Request body

name · string

New name. Cannot be empty if provided.

parent_id · string

New parent folder UUID. Pass null to move to the space root. Omit entirely to leave the parent unchanged.

Example — rename

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

orgId · string · required

Organization UUID.

spaceId · string · required

Space UUID.

nodeId · string · required

Node UUID.

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.