Download File

Audience: Low-code Engineers

Skill Prerequisites: APIs, Actions, Tokens

Returns a file as the response of an API endpoint. The caller receives the file's content, with a content type based on its extension and a file name. Browsers either download the file or show it, depending on Force Download.

It's only available in APIs. It ends the action list, so actions after it don't run.

By default, the action checks that the user calling the API can view the file's folder. The override options skip these checks. Use them with care.

Typical Use Cases

• Give users a secure download link for a file in a protected folder, for example /api/invoice?id=123
• Return a file created earlier in the same API, for example with Generate PDF or Create Excel from List
• Send a file with a friendlier name than the one on disk, for example Invoice-1024.pdf
• Show a PDF or image in the browser instead of downloading it

Don't use it to

• Send a file from a form or listing. Use Send File for Download or Send Plain Text as File Download instead.
• Return text, HTML or JSON. Use Raw Response or one of the JSON actions instead.
• Return a file from an API that has Cache Response turned on and expect caching. This response is never cached. Use File Response instead.

Related Actions

Action Name	Description
File Response	Serves a file by its ID through the site's normal file handling, and supports response caching.
Raw Response	Returns any text content, with your own status code and headers.
Generate PDF	Creates a PDF and stores its file ID or path in tokens.
Create Excel from List	Creates an Excel file and stores its path in tokens.
Send File for Download	Sends a portal file for download from a form.

Which response action should I use?

You want to return	Use
Plain text, HTML, XML or JSON you write yourself	Raw Response
A JSON object built from name/value pairs	New Object as JSON
One item of a list as JSON	Existing Object as JSON
The items of a list as a JSON array	Existing List as JSON
A file, with a file name, permission checks and a download or preview option	Download File
A file by its ID, with response caching	File Response

If no action returns a response, the API returns the text Success.

Input Parameter Reference

The parameters unique to this action are listed below. Review the common parameters for all actions here.

Parameter	Description	Supports Tokens	Default	Required
File Identifier	The file to return. It can be a file ID, for example [FileId], or a path relative to the portal's home folder, for example Invoices/INV-1024.pdf. See File Identifier formats.	Yes	empty string	Yes
New File Name (optional)	The file name the caller receives, without the extension, for example Invoice-[InvoiceNumber]. The original file's extension is added automatically. If it's empty after tokens are replaced, the original file name is used.	Yes	empty string	No
Override User Security Checks	Skips the folder permission check, so anyone who can call the API gets the file, even if they aren't logged in. The file must still be in the current portal.	No	false	No
Override Portal Security Checks	Shown when Override User Security Checks is on. Meant to allow files from any portal's folder, using a path that starts with ~/Portals/. Not recommended. See Considerations.	No	false	No
Override Server Security Checks	Shown when Override Portal Security Checks is on. Allows any file the web server can read, using a full disk path, for example C:\Files\report.pdf. Not recommended.	No	false	No
Force Download	On: the browser downloads the file. Off: the browser can show the file, for example a PDF or image, if it knows how.	No	true	No

File Identifier formats

With the default security checks, or with only Override User Security Checks on, the file must be in the portal's file system. These formats work:

Format	Example
File ID	1024
Path relative to the portal's home folder	Invoices/INV-1024.pdf
Path that includes the portal's home folder	/Portals/0/Invoices/INV-1024.pdf
Full URL of a file in the portal	https://example.com/Portals/0/Invoices/INV-1024.pdf
LinkClick URL	https://example.com/LinkClick.aspx?fileticket=...

When Override Server Security Checks is on too, and the file isn't found in the portal's file system, a full disk path is also accepted.

What the caller receives

Part of the response	Value
Status code	200
Content-Type	Based on the file extension, for example application/pdf. Unknown extensions get application/octet-stream.
Content-Disposition	attachment;filename="<name>" when Force Download is on, inline;filename="<name>" when it's off.
Content-Length	The file size.
Body	The file's content, sent in chunks.

Large files are streamed, and the request isn't stopped by the server's script timeout while the file is sent.

If something goes wrong, the file isn't sent and the API's error handling runs instead. This happens when:

• File Identifier is empty after tokens are replaced
• The file isn't found
• The user doesn't have permission to view the file's folder. The message is Permissions are not met. The file cannot be downloaded.

Without On error actions, the caller gets an error response. See API overview.

Considerations

• Permissions. By default, the user calling the API needs View or Edit permission on the file's folder, and must not be denied View. For an anonymous API, that means the folder must allow the right roles, or you need Override User Security Checks.
• Validate the input. If File Identifier comes from the request, for example [FileId], and you turn on an override, any caller can download any file you allow. Check the value first, for example with a Run SQL Query that confirms the file belongs to the user, and a condition on this action.
• Portal and server overrides. These give access to files outside the portal, limited only by the web server's own permissions. Avoid them. In 1.28, paths that start with ~/ aren't resolved correctly, so use a full disk path if you must use Override Server Security Checks.
• File name. Don't include the extension in New File Name. It's taken from the original file. For example, Report with data.xlsx gives Report.xlsx.
• No caching. This response isn't cached, even when the API has Cache Response turned on. The actions run on every call.
• Final action. Only the first final action that runs returns the response. Use conditions to choose between several responses.

Examples

tip

To understand how to use the below examples, please see Running Examples.

1. Download an invoice by its file ID

This action returns the file whose ID is in the FileId input parameter. It's saved as Invoice-<InvoiceNumber> with the original extension. The folder permissions of the calling user are checked.

{
    "Title": "Download File",
    "ActionType": "DownloadFileResponse",
    "Description": "Return the invoice file",
    "Condition": "[FileId] != \"\"",
    "Parameters": {
        "FileIdentifier": "[FileId]",
        "NewFileName": "Invoice-[InvoiceNumber]",
        "OverrideUserSecurity": false,
        "OverridePortalSecurity": false,
        "OverrideServerSecurity": false,
        "ForceDownload": true
    }
}

2. Show a PDF in the browser

This action returns Documents/Terms.pdf from the portal's home folder. Force Download is off, so the browser can open the PDF in a tab. Override User Security Checks is on, so anonymous callers get the file too.

{
    "Title": "Download File",
    "ActionType": "DownloadFileResponse",
    "Description": "Show the terms PDF",
    "Parameters": {
        "FileIdentifier": "Documents/Terms.pdf",
        "NewFileName": "",
        "OverrideUserSecurity": true,
        "OverridePortalSecurity": false,
        "OverrideServerSecurity": false,
        "ForceDownload": false
    }
}

Revised 09/27/2026