Files

introduction a file represents any file used by your workflows you can download and retrieve a file's metadata from the /files resource retrieve file (metadata) retrieve a file's metadata with an option to generate a pre signed url for easy reference see download file docid 9dvdmpooxgp3thr hxh v if you wish to download the file to your app directly to retrieve a file make an authenticated get request to /file/\ fileid query parameters parameter required value default description example expand no presigned url n/a expand a file response by including a time limited, pre signed url to the file /files/\<file id>?expand=presigned url presigned url expires in no number 300 seconds (5 minutes) the presigned url expiration time in second between 30 and 604800 (1 week) the floyo api will return a validation error if expand=outpus presigned url is not specified /files/\<file id>?expand=presigned url\&presigned url expires in=600 a presigned url is a time limited, self contained url that carries authentication credentials embedded in it, so the client can access a resource directly without going through your server once generated, it is public — anyone in possession of the url can access the resource without further authentication, until the expiry time passes and the url becomes invalid response attributes attribute type desription id string unique id of the file, e g , file ns8kprtb8ljjataa object file returned object type, always file file name string the file name mime type string the file mime type size bytes integer the file size in bytes created at string iso8601 timestamp when the file was created input path string the path to be used as the input file path for any compatible comfyui node presigned url string the optional public presigned url example request curl curl x get https //api floyo ai/files/\<file id>?expand=presigned url \\ h "authorization bearer \<your api key>" \\ h "accept application/json" example response status 200 file retrieved successfully { "id" "file ns8kprtb8ljjataa", "object" "file", "file name" "comfyui 00994 png", "mime type" "image/png", "size bytes" 350983, "created at" "2026 04 21t13 55 32 431054+00 00", "input path" "#inputs/comfyui 00994 png", "presigned url" "https //cdn floyo ai/file ns8kprtb8ljjataa?token=eyjhbgcioijiuzi1niisinr5cci6ikpxvcisimtpzci6inyxin0 eyjmawxlx2lkijoizmlszv9ouzhlufj0yjhmsmphdefbiiwiywtfawqioijqnxjncmnuncisimp0asi6imrhmzgzmtq1ltu3mtutnddjyy1iztc3lwu4zmqyotczodu0nyisimlzcyi6imzsb3lvlwfwasisimf1zci6imzsb3lvlwnkbiisinn1yii6imzpbgvfywnjzxnziiwiawf0ijoxnzc3mzewotg4lcjuymyioje3nzczmta5odgsimv4cci6mtc3nzm3mdk4oh0 6ixooiulm tbuvj5tcy6w eawhovrpvii4 5wshuism" } download file download a file from the floyo cdn if you don't want to generate a presigned url for your file but you're still eager to download it, you can make an authenticated request to the floyo files cdn floyo files cdn base url https //cdn floyo ai/ to download the file make an authenticated get request to https //cdn floyo ai/\<file id>/download this endpoint streams the file directly from the cdn to the client without buffering it in memory, so download performance is determined by the cdn and not the api server the cdn independently validates the bearer token, ensuring the file is only served to authenticated requests even if the cdn endpoint were accessed directly example request curl curl oj https //cdn floyo ai/\<file id>/download \\ h "authorization bearer \<your api key>" if the authentication passes and the file exists, it will be downloaded to your drive upload file introduction the floyo files api allows you to upload files directly to your team's storage using a standard multipart/form data request uploaded files can later be referenced inside workflows, reused across runs, or managed through the files api the upload endpoint supports file uploads using multipart/form data custom destination paths optional server side filename overrides configurable filename conflict handling upload endpoint to upload a file, make an authenticated post request to the floyo files cdn /upload endpoint floyo files cdn upload url https //cdn floyo ai/upload request format uploads must be sent as a multipart/form data request form fields parameter required type default description file yes blob/file n/a the file to upload path no string n/a destination path inside /inputs filename no string n/a override the uploaded filename on conflict no string fail conflict strategy fail or rename parameters file the binary file to upload this parameter is required and must be sent as a blob , file , or binary multipart upload path optional destination path where the file should be uploaded all uploads are stored under the /inputs root directory for example, if path is set to /api/uploads your file will be uploaded to /inputs/api/uploads if omitted, the file will be uploaded to the root /inputs directory filename optional filename override if provided, this value replaces the original uploaded filename on conflict controls how filename conflicts are handled possible values value description fail default value reject the upload if a file with the same name already exists on the destination folder rename automatically renames the file when a filename conflict occurs by appending an incrementing suffix, and returns the final filename in the response for example, if landscape png already exists, the uploaded file may be renamed to landscape (1) png , landscape (2) png , and so on example request the following example will upload a file named landscape png to the /inputs/api/uploads folder, and will be renamed to beautiful landscape png if a file with the same name already exists at the destination, the uploaded file will be automatically renamed to avoid the conflict curl x post "https //cdn floyo ai/upload" \\ h "authorization bearer \<your api key>" \\ f "file=@ /landscape png" \\ f "path=/api/uploads" \\ f "filename=beautiful landscape png" \\ f "on conflict=rename" response status 200 file uploaded successfully returns the uploaded file metadata the input path value can be used as the input file path for any compatible comfyui node { id 'file fd243hoyg1agzcd2', file name 'beautiful landscape (1) png', mime type 'image/png', created at '2026 05 12t18 24 19 278928+00 00', size bytes 7482666, input path '#inputs/api/uploads/beautiful landscape (1) png' } status 409 filename conflict returned when on conflict=fail and a file with the same name already exists in the destination directory the response includes a suggestion field containing the next available filename you can use to retry the upload without conflicts { "error" "upload failed", "message" "a file with the same name already exists at the requested path ", "suggestion" "beautiful landscape (1) png" } upload flow overview build a multipart/form data request attach the file using the file field optionally specify path , filename , and on conflict send the request to /upload receive the uploaded file metadata tips & best practices use rename for automatic conflict handling if your application uploads user generated content, using on conflict=rename helps avoid upload failures caused by duplicate filenames organize uploads using paths use nested paths to keep uploads organized /api/uploads/users /api/uploads/projects /api/uploads/generated preserve original mime types always send the correct mime type when creating the upload blob if the mime type cannot be detected, fallback to application/octet stream