Upload files, versions, and task attachments through the API
Prepare a direct upload, send the file, confirm it, and handle safe retries.
The upload flow has three steps. First, prepare the upload. Next, send the file to the returned URL. Last, confirm the upload with Sydnee.
Which upload route should you use?
Use the preparation and confirmation routes for the item you want to create:
Account file
- Prepare:
POST /v1/accounts/{accountId}/files. - Confirm:
POST /v1/accounts/{accountId}/files/confirm. - Maximum size: 256 MiB.
New file version
- Prepare:
POST /v1/accounts/{accountId}/files/{fileId}/versions. - Confirm:
POST /v1/accounts/{accountId}/files/{fileId}/versions/confirm. - Maximum size: 256 MiB.
Task attachment
- Prepare:
POST /v1/accounts/{accountId}/task-boards/{boardId}/tasks/{taskId}/attachments. - Confirm:
POST /v1/accounts/{accountId}/task-boards/{boardId}/tasks/{taskId}/attachments/confirm. - Maximum size: 25 MiB.
Account file and version names can have up to 255 characters. Task attachment names can have up to 80 characters. A version note can have up to 10,000 characters.
How do you prepare the upload?
Send the file details as JSON to the preparation route. Use your Sydnee bearer key.
The body includes:
name: The original file name.size: The exact file size in bytes.mimeType: The media type intype/subtypeform.folderId: The optional folder for an account file. Leave it out or usenullfor the account root.changeNote: An optional note for a new file version.
The response has an upload object. It includes method, url, fields, token, expiresAt, confirmHref, and maxBytes.
Each API key can prepare 20 uploads per minute. These calls also count toward the workspace write limit. Follow Retry-After after a 429 response.
How do you send the file?
Build a multipart form from the preparation response:
- Use the returned
upload.methodandupload.url. - Add each item from
upload.fields. Keep its name and value as shown. - Add the file last. Name that form field
file. - Send the form before
upload.expiresAt.
The file must match the name, size, and media type you prepared. If the file changes, prepare a new upload before you send it.
How do you confirm the upload?
Send the returned token to upload.confirmHref with the normal Sydnee bearer key:
{
"token": "opaque_upload_token"
}The first confirmation returns 201. It creates the file, version, or attachment. The same confirmation can run again safely. It returns the saved result with 200. This helps when an integration misses the first response.
Confirm before upload.expiresAt. Preparing and sending the file without confirmation does not create the Sydnee record.
Sydnee may adjust supported task attachment images during this step. Use the attachment details in the response as the saved result.
How do you delete a task attachment?
Use this route for a task attachment uploaded through the public API:
DELETE /v1/accounts/{accountId}/task-boards/{boardId}/tasks/{taskId}/attachments/{attachmentId}Use the numeric attachment ID from the confirmation or task detail. This route removes only task attachments made through this public API flow. Account files and other task attachments stay in place.
How do you fix an upload problem?
Start with the HTTP status and error.details.reason. Fix API and Zapier problems explains upload limits, storage conflicts, expired tokens, and safe retry steps.