Files

Tags: files, storage

File upload and management

In the product: Files

Resources

Request and response models used by the endpoints on this page.

ConvertedFileResponse

Field	Type	Required	Description
content	String	✓
filename	String	✓
format	Literal[text, markdown, pdf]	✓
message	String	✓

Example:

{
  "content": "string"  // String,
  "format": null  // Literal[text, markdown, pdf],
  "filename": "string"  // String,
  "message": "string"  // String
}

Endpoints

• GET /api/v2/w/{workspace_uuid}/files - List
• POST /api/v2/w/{workspace_uuid}/files - Create
• GET /api/v2/w/{workspace_uuid}/files/resolve-path - Resolve Path
• POST /api/v2/w/{workspace_uuid}/files/upload-url - Upload Url
• DELETE /api/v2/w/{workspace_uuid}/files/{file_id} - Delete File Id
• GET /api/v2/w/{workspace_uuid}/files/{file_id} - Get File Id
• PUT /api/v2/w/{workspace_uuid}/files/{file_id} - Update File Id
• POST /api/v2/w/{workspace_uuid}/files/{file_id}/convert - Convert

List

GET /api/v2/w/{workspace_uuid}/files

Description:

List all files for the authenticated user.

Authorization: Requires files:read scope

Parameters:

• folder_id (Integer)
• page (Integer) — min: 1
• pageSize (Integer) — min: 1, max: 100
• sortBy (FileSortField)
• sortOrder (SortOrder)
• search (String)

Response: See PaginatedResponse[FileResponse]

---

Create

POST /api/v2/w/{workspace_uuid}/files

Description:

Create a new file.

Authorization: Requires files:write scope

Parameters:

• file (CreateFileRequest)

---

Resolve Path

GET /api/v2/w/{workspace_uuid}/files/resolve-path

Description:

Resolve a wiki-style relative path to a file.

Powers relative markdown links/images in the file browser: path is resolved against folderId (the linking document's folder; omit for the workspace root), with ../. segments and an optional .md extension fallback handled server-side.

Authorization: Requires files:read scope

Parameters:

• path (String)
• folderId (Integer)

---

Upload Url

POST /api/v2/w/{workspace_uuid}/files/upload-url

Description:

Generate a presigned URL for uploading a file.

Authorization: Requires files:write scope

Parameters:

• file_request (FileUploadRequest)

Response: See FileUploadResponse

---

Delete File Id

DELETE /api/v2/w/{workspace_uuid}/files/{file_id}

Description:

Delete a file (tombstone-preserving; version history survives).

Authorization: Requires scopes: files:write, files:admin

Parameters:

• file_id (Integer)

---

Get File Id

GET /api/v2/w/{workspace_uuid}/files/{file_id}

Description:

Get a specific file by ID.

Authorization: Requires files:read scope

Parameters:

• file_id (Integer)

---

Update File Id

PUT /api/v2/w/{workspace_uuid}/files/{file_id}

Description:

Update an existing file.

Authorization: Requires files:write scope

Parameters:

• file_id (Integer)
• file (UpdateFileRequest)

---

Convert

POST /api/v2/w/{workspace_uuid}/files/{file_id}/convert

Description:

Convert a file to various formats.

Returns: A ConvertedFileResponse containing the converted content and file metadata.

Authorization: Requires files:read scope

Parameters:

• file_id (Integer)
• format (Literal['text', 'markdown', 'pdf'])

Response: See ConvertedFileResponse

---