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",
  "format": "text",
  "filename": "string",
  "message": "string"
}

CreateFileRequest

Field	Type	Required	Description
access	String		Default: private
cdnUrl	String
data	bytes
dataBase64	String
description	String
externalId	String
fileSize	Integer
filename	String	✓
folderId	Integer
labelIds	Array
mimeType	String	✓
oauthCredentialUuid	String
overwrite	Boolean		Default: False
s3Key	String
siteId	Integer
subjectMemberId	Integer
title	String

Example:

{
  "filename": "string",
  "mimeType": "string",
  "access": "private",
  "overwrite": false
}

FileFolderResponse

Field	Type	Required	Description
access	String		Default: private
ancestors	Array<FolderPathSegment>		Default: []
childCount	Integer		Default: 0
createdAt	DateTime	✓
description	String
fileCount	Integer		Default: 0
id	Integer	✓
index	Boolean		Default: False
indexingCompletedAt	DateTime
indexingStartedAt	DateTime
name	String	✓
ownerId	Integer
ownerName	String
parentId	Integer
path	String
shareable	Boolean		Default: False
updatedAt	DateTime	✓
uuid	String	✓

Example:

{
  "id": 0,
  "name": "string",
  "uuid": "string",
  "childCount": 0,
  "fileCount": 0,
  "access": "private",
  "shareable": false,
  "index": false,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "ancestors": []
}

FileLabelResponse

Field	Type	Required	Description
color	String	✓
description	String	✓
id	Integer	✓
name	String	✓
uuid	String	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "name": "string",
  "color": "string",
  "description": "string"
}

FileResponse

Field	Type	Required	Description
access	String		Default: private
accessMode	Integer
cdnUrl	String	✓
choicePrompt	String
createdAt	DateTime	✓
currentVersionNumber	Integer		Default: 0
data	String	✓
description	String	✓
externalId	String	✓
fileSize	Integer	✓
filename	String	✓
folder	FileFolderResponse | null	✓
folderAncestorIds	Array		Default: []
folderId	Integer	✓
id	Integer	✓
isS3Stored	Boolean		Default: False
labels	Array<FileLabelResponse> | null
lastEditedByMemberId	Integer
mimeType	String	✓
ownerId	Integer
ownerName	String
permissions	Integer		Default: 0
shareCount	Integer		Default: 0
siteId	Integer	✓
subjectMemberId	Integer
title	String	✓
updatedAt	DateTime	✓
uuid	String	✓

Example:

{
  "id": 0,
  "uuid": "string",
  "title": "string",
  "description": "string",
  "filename": "string",
  "mimeType": "string",
  "folderId": 0,
  "folderAncestorIds": [],
  "siteId": 0,
  "externalId": "string",
  "access": "private",
  "folder": null,
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "data": "string",
  "cdnUrl": "string",
  "fileSize": 0,
  "isS3Stored": false,
  "permissions": 0,
  "shareCount": 0,
  "currentVersionNumber": 0
}

FileUploadRequest

Field	Type	Required	Description
contentType	String	✓
fileExtension	String	✓

Example:

{
  "contentType": "string",
  "fileExtension": "string"
}

FileUploadResponse

Field	Type	Required	Description
fields	Dict[str, str]	✓
fileUrl	String	✓
uploadUrl	String	✓

Example:

{
  "uploadUrl": "string",
  "fields": {},
  "fileUrl": "string"
}

FolderPathSegment

Field	Type	Required	Description
id	Integer	✓
name	String	✓

Example:

{
  "id": 0,
  "name": "string"
}

PaginatedResponse[FileResponse]

Field	Type	Required	Description
items	Array<FileResponse>	✓
page	Integer	✓
pageSize	Integer	✓
total	Integer	✓
totalPages	Integer	✓

Example:

{
  "items": [],
  "total": 0,
  "page": 0,
  "pageSize": 0,
  "totalPages": 0
}

UpdateFileRequest

Field	Type	Required	Description
access	String
baseVersionNumber	Integer
data	bytes
description	String
externalId	String
filename	String
folderId	Integer
labelIds	Array
mimeType	String
oauthCredentialUuid	Integer
siteId	Integer
subjectMemberId	Integer
title	String

Example:

{}

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)

Response: FileResponse

---

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. A /gr/workspace/… or /gr/home/… path resolves from that root instead, with a read check on the root, every folder below it and the file; .. is refused there and there is no .md fallback.

Authorization: Requires files:read scope

Parameters:

• path (String)
• folderId (Integer)

Response: FileResponse

---

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)

Response: dict[str, str]

---

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)

Response: FileResponse

---

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)

Response: FileResponse

---

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

---