An uploaded file attached to a project, task, document, message or folder. There is no content-type field: infer it from the extension in name.
List Files
List files. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 12 fields. Ordered by -createdAt unless you pass sort.
Required scope: files:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: -createdAt.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
purgeAt[null]Filter where purgeAt is null (pass true).
purgeAt[notNull]Filter where purgeAt is not null (pass true).
purgeAt[gt]Filter where purgeAt is greater than.
purgeAt[gte]Filter where purgeAt is greater than or equal to.
purgeAt[lt]Filter where purgeAt is less than.
purgeAt[lte]Filter where purgeAt is less than or equal to.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
taskId[eq]Filter where taskId equals.
taskId[in]Filter where taskId is one of (comma-separated list).
documentId[eq]Filter where documentId equals.
documentId[in]Filter where documentId is one of (comma-separated list).
messageId[eq]Filter where messageId equals.
messageId[in]Filter where messageId is one of (comma-separated list).
folderId[eq]Filter where folderId equals.
folderId[in]Filter where folderId is one of (comma-separated list).
annotationTaskId[eq]Filter where annotationTaskId equals.
annotationTaskId[in]Filter where annotationTaskId is one of (comma-separated list).
uploaderId[eq]Filter where uploaderId equals.
uploaderId[in]Filter where uploaderId is one of (comma-separated list).
processed[eq]Filter where processed equals.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
updatedAt[gt]Filter where updatedAt is greater than.
updatedAt[gte]Filter where updatedAt is greater than or equal to.
updatedAt[lt]Filter where updatedAt is less than.
updatedAt[lte]Filter where updatedAt is less than or equal to.
List Files › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Create File
Create a File. Server-assigned fields are ignored if sent. This REGISTERS METADATA — it does not upload bytes. Get the bytes into storage first with the createUploadUrl operation (which returns an uploadKey plus a presigned URL to PUT to), then create the file passing that uploadKey, the name and the size in bytes. createFromContent and uploadFromUrl do both halves in one call. AT LEAST ONE parent is required: projectId, taskId, documentId, messageId or folderId — a create with none of them is rejected. A file is capped at 2 GB, and each team has a total storage quota; exceeding either is rejected.
Required scope: files:write
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create File › Request Body
nameFile name, WITH its extension — there is no content-type field, so the extension is how a consumer tells a PDF from a PNG.
sizeSize of the uploaded file in bytes. Required — pass the byte count of what you uploaded. Maximum 2 GB per file, and the upload also has to fit your team's remaining storage quota.
uploadKeyStorage key of the already-uploaded bytes: call the createUploadUrl operation, PUT the bytes to the presigned URL it returns, then pass its uploadKey here verbatim. Create REGISTERS metadata; it does not upload bytes.
projectIdAttach the file to this project (one context per file).
taskIdAttach the file to this task (one context per file).
documentIdAttach the file to this document (one context per file).
messageIdAttach the file to this message (one context per file).
folderIdPlace the file in this folder. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · requires: projectId | |
| type = object · requires: taskId | |
| type = object · requires: documentId | |
| type = object · requires: messageId | |
| type = object · requires: folderId |
projectIdAttach the file to this project (one context per file).
nameFile name, WITH its extension — there is no content-type field, so the extension is how a consumer tells a PDF from a PNG.
sizeSize of the uploaded file in bytes. Required — pass the byte count of what you uploaded. Maximum 2 GB per file, and the upload also has to fit your team's remaining storage quota.
uploadKeyStorage key of the already-uploaded bytes: call the createUploadUrl operation, PUT the bytes to the presigned URL it returns, then pass its uploadKey here verbatim. Create REGISTERS metadata; it does not upload bytes.
taskIdAttach the file to this task (one context per file).
documentIdAttach the file to this document (one context per file).
messageIdAttach the file to this message (one context per file).
folderIdPlace the file in this folder. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
Create File › Responses
Created
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameFile name, WITH its extension — there is no content-type field on a file, so the extension in this name is how a consumer tells a PDF from a PNG. 1–255 characters after trimming; a blank name is rejected.
sizeSize of the uploaded file in bytes. Required on create — pass the byte count of what you uploaded. Maximum 2,147,483,646 (2 GB) per file, and the upload also has to fit your team's remaining storage quota; exceeding either is rejected.
urlTime-limited download URL for the stored file. Read-only — set the bytes at creation with uploadKey; they never move afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdMember who soft-deleted this resource (server-stamped). A member id — resolve it with GET /members/{id}.
processedFalse until server-side post-processing (thumbnail generation, virus scanning) finishes — thumbnail and download may be null until then. Typically a few seconds.
downloadAlternate time-limited download URL for the same bytes as url. Read-only.
thumbnailPreview-image URL for image and video files; null for everything else, and null until processed becomes true. Read-only.
folderStackThe folder path this file sits in, from the project root down to its direct parent. Derived by the server from folderId.
Team members subscribed to this file — they are notified when it changes. Populated only when you ask for it with ?expand=subscribers; add and remove them with POST / DELETE /files/{id}/subscribers.
Labels attached to this file. Populated only when you ask for it with ?expand=labels; add and remove them with POST / DELETE /files/{id}/labels.
uploaderIdThe team member who uploaded the file — a member id, so resolve it with ?expand=uploader or GET /members/{id}. Null when uploaded by an agent or an integration — see createdByActorType.
projectIdAttach the file to this project. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
taskIdAttach the file to this task. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
documentIdAttach the file to this document. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
messageIdAttach the file to this message. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
folderIdPlace the file in this folder. At least one of projectId, taskId, documentId, messageId or folderId is required on create. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
annotationTaskIdThe task that holds this file's annotation thread, created when the file is opened in annotation mode. Read-only.
The related Team Member, present only when you pass ?expand=uploader.
The related Team Member, present only when you pass ?expand=deletedBy.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Project, present only when you pass ?expand=project.
The related Task, present only when you pass ?expand=task.
The related Document, present only when you pass ?expand=document.
The related Message, present only when you pass ?expand=message.
The related Task, present only when you pass ?expand=annotationTask.
The linked Annotation rows, present only when you pass ?expand=annotations.
Get File
Retrieve a single File by id.
Required scope: files:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get File › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameFile name, WITH its extension — there is no content-type field on a file, so the extension in this name is how a consumer tells a PDF from a PNG. 1–255 characters after trimming; a blank name is rejected.
sizeSize of the uploaded file in bytes. Required on create — pass the byte count of what you uploaded. Maximum 2,147,483,646 (2 GB) per file, and the upload also has to fit your team's remaining storage quota; exceeding either is rejected.
urlTime-limited download URL for the stored file. Read-only — set the bytes at creation with uploadKey; they never move afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdMember who soft-deleted this resource (server-stamped). A member id — resolve it with GET /members/{id}.
processedFalse until server-side post-processing (thumbnail generation, virus scanning) finishes — thumbnail and download may be null until then. Typically a few seconds.
downloadAlternate time-limited download URL for the same bytes as url. Read-only.
thumbnailPreview-image URL for image and video files; null for everything else, and null until processed becomes true. Read-only.
folderStackThe folder path this file sits in, from the project root down to its direct parent. Derived by the server from folderId.
Team members subscribed to this file — they are notified when it changes. Populated only when you ask for it with ?expand=subscribers; add and remove them with POST / DELETE /files/{id}/subscribers.
Labels attached to this file. Populated only when you ask for it with ?expand=labels; add and remove them with POST / DELETE /files/{id}/labels.
uploaderIdThe team member who uploaded the file — a member id, so resolve it with ?expand=uploader or GET /members/{id}. Null when uploaded by an agent or an integration — see createdByActorType.
projectIdAttach the file to this project. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
taskIdAttach the file to this task. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
documentIdAttach the file to this document. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
messageIdAttach the file to this message. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
folderIdPlace the file in this folder. At least one of projectId, taskId, documentId, messageId or folderId is required on create. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
annotationTaskIdThe task that holds this file's annotation thread, created when the file is opened in annotation mode. Read-only.
The related Team Member, present only when you pass ?expand=uploader.
The related Team Member, present only when you pass ?expand=deletedBy.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Project, present only when you pass ?expand=project.
The related Task, present only when you pass ?expand=task.
The related Document, present only when you pass ?expand=document.
The related Message, present only when you pass ?expand=message.
The related Task, present only when you pass ?expand=annotationTask.
The linked Annotation rows, present only when you pass ?expand=annotations.
Delete File
Move this File to trash. It disappears from list results immediately and is permanently purged after a 30-day retention window; until then it can be restored.
Required scope: files:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Delete File › Responses
No Content
Update File
Partially update a File. Only the fields you send are changed.
Required scope: files:write
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Update File › Request Body
nameFile name, WITH its extension — there is no content-type field, so the extension is how a consumer tells a PDF from a PNG.
sizeSize of the uploaded file in bytes. Required — pass the byte count of what you uploaded. Maximum 2 GB per file, and the upload also has to fit your team's remaining storage quota.
folderIdPlace the file in this folder. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
expectedUpdatedAtOptional concurrency guard: the updatedAt you last read. If the resource has changed since, the update is rejected with 409 instead of overwriting the other writer. Re-read, re-derive your change from the current values, and retry with the fresh updatedAt.
Update File › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameFile name, WITH its extension — there is no content-type field on a file, so the extension in this name is how a consumer tells a PDF from a PNG. 1–255 characters after trimming; a blank name is rejected.
sizeSize of the uploaded file in bytes. Required on create — pass the byte count of what you uploaded. Maximum 2,147,483,646 (2 GB) per file, and the upload also has to fit your team's remaining storage quota; exceeding either is rejected.
urlTime-limited download URL for the stored file. Read-only — set the bytes at creation with uploadKey; they never move afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdMember who soft-deleted this resource (server-stamped). A member id — resolve it with GET /members/{id}.
processedFalse until server-side post-processing (thumbnail generation, virus scanning) finishes — thumbnail and download may be null until then. Typically a few seconds.
downloadAlternate time-limited download URL for the same bytes as url. Read-only.
thumbnailPreview-image URL for image and video files; null for everything else, and null until processed becomes true. Read-only.
folderStackThe folder path this file sits in, from the project root down to its direct parent. Derived by the server from folderId.
Team members subscribed to this file — they are notified when it changes. Populated only when you ask for it with ?expand=subscribers; add and remove them with POST / DELETE /files/{id}/subscribers.
Labels attached to this file. Populated only when you ask for it with ?expand=labels; add and remove them with POST / DELETE /files/{id}/labels.
uploaderIdThe team member who uploaded the file — a member id, so resolve it with ?expand=uploader or GET /members/{id}. Null when uploaded by an agent or an integration — see createdByActorType.
projectIdAttach the file to this project. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
taskIdAttach the file to this task. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
documentIdAttach the file to this document. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
messageIdAttach the file to this message. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
folderIdPlace the file in this folder. At least one of projectId, taskId, documentId, messageId or folderId is required on create. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
annotationTaskIdThe task that holds this file's annotation thread, created when the file is opened in annotation mode. Read-only.
The related Team Member, present only when you pass ?expand=uploader.
The related Team Member, present only when you pass ?expand=deletedBy.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Project, present only when you pass ?expand=project.
The related Task, present only when you pass ?expand=task.
The related Document, present only when you pass ?expand=document.
The related Message, present only when you pass ?expand=message.
The related Task, present only when you pass ?expand=annotationTask.
The linked Annotation rows, present only when you pass ?expand=annotations.
Search Files
Full-text ranked search across files. Ranked by relevance; pages are capped at 200 results. Filterable by 12 fields.
Required scope: files:read
query Parameters
qFull-text search query. Trimmed before matching; URLs, e-mail addresses and HTML markup are rejected.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
purgeAt[null]Filter where purgeAt is null (pass true).
purgeAt[notNull]Filter where purgeAt is not null (pass true).
purgeAt[gt]Filter where purgeAt is greater than.
purgeAt[gte]Filter where purgeAt is greater than or equal to.
purgeAt[lt]Filter where purgeAt is less than.
purgeAt[lte]Filter where purgeAt is less than or equal to.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
taskId[eq]Filter where taskId equals.
taskId[in]Filter where taskId is one of (comma-separated list).
documentId[eq]Filter where documentId equals.
documentId[in]Filter where documentId is one of (comma-separated list).
messageId[eq]Filter where messageId equals.
messageId[in]Filter where messageId is one of (comma-separated list).
folderId[eq]Filter where folderId equals.
folderId[in]Filter where folderId is one of (comma-separated list).
annotationTaskId[eq]Filter where annotationTaskId equals.
annotationTaskId[in]Filter where annotationTaskId is one of (comma-separated list).
uploaderId[eq]Filter where uploaderId equals.
uploaderId[in]Filter where uploaderId is one of (comma-separated list).
processed[eq]Filter where processed equals.
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
updatedAt[gt]Filter where updatedAt is greater than.
updatedAt[gte]Filter where updatedAt is greater than or equal to.
updatedAt[lt]Filter where updatedAt is less than.
updatedAt[lte]Filter where updatedAt is less than or equal to.
Search Files › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Add subscribers to a File
Link the given ids to this File as subscribers. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete subscribers set afterwards.
Required scopes: files:write files:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add subscribers to a File › Request Body
idsTeam Members to add or remove, by id.
Add subscribers to a File › Responses
OK
The complete subscribers set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove subscribers from a File
Unlink the given ids from this File's subscribers. Removing one that is not linked changes nothing. Returns the complete subscribers set afterwards.
Required scopes: files:write files:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove subscribers from a File › Request Body
idsTeam Members to add or remove, by id.
Remove subscribers from a File › Responses
OK
The complete subscribers set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).
Add labels to a File
Link the given ids to this File as labels. Adds to the existing set rather than replacing it, and adding one that is already linked changes nothing. Returns the complete labels set afterwards.
Required scopes: files:write files:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Add labels to a File › Responses
OK
The complete labels set after the change.
affectedIdsThe ids that were actually linked (ones already linked are omitted).
missingIdsIds you sent that do not exist or are not visible to this token.
Remove labels from a File
Unlink the given ids from this File's labels. Removing one that is not linked changes nothing. Returns the complete labels set afterwards.
Required scopes: files:write files:link
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Remove labels from a File › Responses
OK
The complete labels set after the change.
affectedIdsThe ids that were actually unlinked (ones not linked are omitted).
Create upload url (File)
Mint a presigned S3 upload URL — step 1 of uploading a new file. Step 2: HTTP PUT the raw bytes to uploadUrl sending exactly headers. Step 3: create the file with POST /files, passing the returned uploadKey, plus name, size (byte count of what you uploaded), and exactly ONE parent — projectId, taskId, documentId or messageId. uploadUrl expires (~15 min); max 2 GB. If your client cannot make raw HTTP PUTs (sandboxed environments), use createFromContent instead (max 3 MB). To attach an asset you only have a URL for, use uploadFromUrl instead (max 25 MB).
Required scope: files:write
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create upload url (File) › Request Body
nameFile name WITH extension — used to derive content type and the stored object name.
contentTypeIANA media type to store. Omit and the server infers it — for uploadFromUrl from the fetched response Content-Type, otherwise from the content prefix or the name extension.
Create upload url (File) › Responses
OK
uploadKeyPass this VERBATIM as uploadKey when creating the file row.
uploadUrlPresigned S3 URL — HTTP PUT the raw file bytes here.
Send exactly these headers on the PUT.
expiresAtISO timestamp when uploadUrl stops working.
Create from content (File)
Create a file from inline base64 content in ONE call — for clients that cannot HTTP PUT raw bytes to S3 (sandboxed/egress-blocked environments); max 3 MB decoded. Prefer createUploadUrl + HTTP PUT when your environment has open egress — base64 costs ~1.37x the bytes and transits your context. name needs the file extension. Pass at least one parent — taskId, projectId, documentId, messageId or folderId; with only taskId the server derives the project from the task. If you only have a URL to the asset, use uploadFromUrl.
Required scope: files:write
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Create from content (File) › Request Body
nameFile name WITH extension — the extension drives content-type inference and the stored object name.
contentBase64File bytes as base64 (standard or url-safe alphabet; an optional data:<mime>;base64, prefix is accepted). Max 3 MB decoded.
contentTypeIANA media type of the bytes. Omit to infer from a data: URI prefix or the name extension.
projectIdAttach the file to this project.
taskIdAttach the file to this task (the project is derived from it).
documentIdAttach the file to this document.
messageIdAttach the file to this message.
folderIdPlace the file in this folder.
Create from content (File) › Responses
OK
idId of the created file row.
nameStored file name (echoes what you sent).
sizeDecoded byte count of the stored object (server-computed).
urlPresigned download URL for the stored object (null only if presigning failed — the file still exists).
idempotentReplayTrue when this call replayed an earlier identical one; nothing was uploaded this time.
Upload from url (File)
Create a file from a public http/https URL in ONE call — the SERVER fetches it, for a client that has the address but cannot fetch the bytes (egress-blocked/sandboxed environments); the URL goes in sourceUrl (not uploadKey, which on file create is the pointer to already-uploaded bytes, and not url, which is the download link on a stored file), max 25 MB, and at least one parent is required (taskId, projectId, documentId, messageId or folderId). Up to 3 redirects; private/internal addresses are refused. name defaults to the URL's filename. With only taskId the server derives projectId. If you HAVE the bytes and they are ≤3 MB use createFromContent; for big files with open egress use createUploadUrl + HTTP PUT.
Required scope: files:write
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Upload from url (File) › Request Body
sourceUrlPublic http/https URL the SERVER fetches the bytes from. Up to 3 redirects are followed (every hop is re-validated); max 25 MB; default ports only. URLs with embedded credentials are refused, as are private/internal addresses.
nameFile name WITH extension. Omit to use the basename of the final URL path (after redirects).
contentTypeIANA media type to store, overriding the response Content-Type. Omit to use that header, then the name extension, then application/octet-stream.
projectIdAttach the file to this project.
taskIdAttach the file to this task (the project is derived from it).
documentIdAttach the file to this document.
messageIdAttach the file to this message.
folderIdPlace the file in this folder.
Upload from url (File) › Responses
OK
idId of the created file row.
nameStored file name (what you sent, or the name derived from the URL).
sizeByte count of the fetched object as stored (server-computed).
urlPresigned download URL for the stored object (null only if presigning failed — the file still exists).
idempotentReplayTrue when this call replayed an earlier identical one; nothing was fetched or stored this time.
Restore File
Restore a File that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.
Required scope: files:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the File.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Restore File › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
nameFile name, WITH its extension — there is no content-type field on a file, so the extension in this name is how a consumer tells a PDF from a PNG. 1–255 characters after trimming; a blank name is rejected.
sizeSize of the uploaded file in bytes. Required on create — pass the byte count of what you uploaded. Maximum 2,147,483,646 (2 GB) per file, and the upload also has to fit your team's remaining storage quota; exceeding either is rejected.
urlTime-limited download URL for the stored file. Read-only — set the bytes at creation with uploadKey; they never move afterwards.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdMember who soft-deleted this resource (server-stamped). A member id — resolve it with GET /members/{id}.
processedFalse until server-side post-processing (thumbnail generation, virus scanning) finishes — thumbnail and download may be null until then. Typically a few seconds.
downloadAlternate time-limited download URL for the same bytes as url. Read-only.
thumbnailPreview-image URL for image and video files; null for everything else, and null until processed becomes true. Read-only.
folderStackThe folder path this file sits in, from the project root down to its direct parent. Derived by the server from folderId.
Team members subscribed to this file — they are notified when it changes. Populated only when you ask for it with ?expand=subscribers; add and remove them with POST / DELETE /files/{id}/subscribers.
Labels attached to this file. Populated only when you ask for it with ?expand=labels; add and remove them with POST / DELETE /files/{id}/labels.
uploaderIdThe team member who uploaded the file — a member id, so resolve it with ?expand=uploader or GET /members/{id}. Null when uploaded by an agent or an integration — see createdByActorType.
projectIdAttach the file to this project. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
taskIdAttach the file to this task. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
documentIdAttach the file to this document. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
messageIdAttach the file to this message. At least one of projectId, taskId, documentId, messageId or folderId is required on create. Fixed at upload.
folderIdPlace the file in this folder. At least one of projectId, taskId, documentId, messageId or folderId is required on create. A file's project / task / document / message parent is fixed at upload; only its folder can be changed afterwards.
annotationTaskIdThe task that holds this file's annotation thread, created when the file is opened in annotation mode. Read-only.