Floyo API - Files

introduction a file represents any file used by your workflows you can download and retrieve a file's metadata from the /files resource browsing files browse returns a paginated collection of files and folders for a path in your team's storage use query parameters to filter, search, and sort the result set pass the cursor from a previous response to fetch the next page when has more is true to browse your files make an authenticated get request to /files the path query parameter is required use / to list the storage root, or a folder path such as /inputs , /outputs , or /inputs/api/uploads query parameters parameter required value default description example path yes string n/a folder path to list paths are normalized to a single leading / and no trailing / (except root / ) and segments are not allowed /files?path=/inputs search no string (3–128 characters) n/a case insensitive search against the file or folder name /files?path=/inputs\&search=landscape sort no created at , size bytes , or name , optionally followed by asc or desc created at desc sort order for the result set when sort is omitted entirely, items are sorted by created at descending (newest first) /files?path=/outputs\&sort=name asc limit no integer between 10 and 100 50 maximum number of items to return in a single page /files?path=/inputs\&limit=75 cursor no string n/a opaque pagination cursor returned by a previous browse response use with the same path , filters, search, and sort values as the request that produced the cursor /files?path=/inputs\&cursor=eyjpzci6imzpbgvfmtizin0 created at\[gte] no iso 8601 datetime or unix timestamp in seconds n/a include items created at or after this timestamp /files?path=/inputs\&created at\[gte]=1777593599 created at\[lte] no iso 8601 datetime or unix timestamp in seconds n/a include items created at or before this timestamp must be greater than or equal to created at\[gte] when both are set /files?path=/inputs\&created at\[lte]=2026 04 30t23 59 59z size bytes\[gte] no integer ≥ 0 n/a include items whose size is greater than or equal to this value, in bytes /files?path=/outputs\&size bytes\[gte]=1000000 size bytes\[lte] no integer ≥ 0 n/a include items whose size is less than or equal to this value, in bytes must be greater than or equal to size bytes\[gte] when both are set /files?path=/outputs\&size bytes\[lte]=5000000 response attributes attribute type description path string the normalized folder path that was listed items array array of file and folder objects matching the query cursor string | null pagination cursor to pass as the cursor query parameter on the next request null when there is no next page has more boolean whether additional items are available beyond the current page each object in items includes the following attributes attribute type description id string unique id of the file or folder, e g , file ns8kprtb8ljjataa object file | folder returned object type name string the file or folder name type string for folders, always folder for files, the mime type (e g , image/png ) size bytes integer the size in bytes full path string the full path of the item in team storage (without a leading / ), e g , inputs/api/uploads/landscape png input path string present when the item can be referenced as a workflow input the path to be used as the input file path for any compatible comfyui node created at string iso8601 timestamp when the item was created updated at string iso8601 timestamp when the item was last updated example requests list the 25 newest items under /inputs curl x get "https //api floyo ai/files?path=/inputs\&sort=created at desc\&limit=25" \\ h "authorization bearer \<your api key>" \\ h "accept application/json" search files by name "dancer" , created after august 2, 2026 at 14 00 utc, sorted by size curl curl x get "https //api floyo ai/files?path=/inputs\&search=dancer\&created at\[gte]=2026 08 02t14 00 00z\&sort=size bytes desc" \\ h "authorization bearer \<your api key>" \\ h "accept application/json" list 100 files between 5 and 10 megabytes, sorted by oldest first curl curl x get "https //api floyo ai/files?path=/inputs\&size bytes\[gte]=5000000\&size bytes\[lte]=10000000\&sort=created at asc\&limit=100" \\ h "authorization bearer \<your api key>" \\ h "accept application/json" example response { "path" "/inputs", "items" \[ { "id" "file abc123xyz789abcd", "object" "folder", "name" "api", "type" "folder", "size bytes" 7482666, "full path" "inputs/api", "input path" "#inputs/api", "created at" "2026 05 12t18 24 19 278928+00 00", "updated at" "2026 05 12t18 24 19 278928+00 00" }, { "id" "file ns8kprtb8ljjataa", "object" "file", "name" "comfyui 00994 png", "type" "image/png", "size bytes" 350983, "full path" "inputs/comfyui 00994 png", "input path" "#inputs/comfyui 00994 png", "created at" "2026 04 21t13 55 32 431054+00 00", "updated at" "2026 04 21t13 55 32 431054+00 00" } ], "cursor" "eyjpzci6imzpbgvftlm4s1bsdgi4tepqyxrbqsj9", "has more" true } error responses status 400 invalid query parameters { "error" "invalid request", "message" "one or more request parameters are invalid ", "details" { "path" "a path is required", "limit" "must be at least 25" } } browsing tips & best practices start from a known root list / to discover top level folders, then drill into /inputs or /outputs (and nested paths) as needed reuse input path in workflows when an item includes input path , you can pass that value directly as the input file path for any compatible comfyui node — the same way you would after uploading a file or retrieving file metadata paginate with stable filters when following a cursor , keep the same path , search , sort , and filter parameters as the request that produced the cursor changing them between pages can return unexpected results 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 /files/\ 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 deleting files and folders delete a file or folder from your team's storage by its unique id files and folders share the same id format (e g , file ns8kprtb8ljjataa ) to delete a file or folder make an authenticated delete request to /files/\<file id> deletion is permanent deleted files and folders cannot be recovered through the floyo api query parameters parameter required value default description example recursive no true , false false when true , delete a folder and all of its contents required when deleting a non empty folder ignored for file deletes /files/\<file id>?recursive=true response attributes when a file is deleted attribute type description id string unique id of the deleted file object file returned object type, always file full path string the full path of the deleted file when a folder is deleted attribute type description id string unique id of the deleted folder object folder returned object type, always folder full path string the full path of the deleted folder delete count integer number of items deleted (including the folder itself and its contents when recursive=true ) example request delete a single file curl curl x delete "https //api floyo ai/files/\<file id>" \\ h "authorization bearer \<your api key>" \\ h "accept application/json" delete a folder and its contents curl curl x delete "https //api floyo ai/files/\<file id>?recursive=true" \\ h "authorization bearer \<your api key>" \\ h "accept application/json" example responses status 200 file deleted successfully { "id" "file ns8kprtb8ljjataa", "object" "file", "full path" "outputs/comfyui 00994 png" } status 200 folder deleted successfully { "id" "file fd243hoyg1agzcd2", "object" "folder", "full path" "inputs/api/uploads", "delete count" 12 } status 403 locked item returned when the target item is locked and cannot be deleted { "error" "forbidden", "message" "this item is locked and cannot be deleted " } status 404 file or folder not found { "error" "not found", "message" "the file or folder you requested to delete was not found " } status 409 folder is not empty returned when deleting a non empty folder without recursive=true { "error" "conflict", "message" "folder is not empty set recursive=true to delete the folder and its contents " } tips & best practices prefer deleting by id from a browse response use browsing your files to locate the item, then pass its id to this endpoint that avoids guessing paths and makes it clear whether you are deleting a file or a folder use recursive=true only when you intend to wipe a folder omitting recursive (or setting recursive=false ) protects you from accidentally deleting a folder that still contains files set recursive=true only when you explicitly want to remove the folder and everything inside it top level folders are protected root folders such as inputs and outputs cannot be deleted delete specific files or nested folders inside them instead