Floyo API - Files

41 min

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 -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 -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 FileDownload File 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 -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 -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 -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 -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.