File Response

Audience: Low-code Engineers

Skill Prerequisites: APIs, Actions, Tokens

Returns a portal file, by its file ID, as the response of an API endpoint. The server transfers the request to the file's URL, so the file is served by the site's normal file handling, as if the caller had opened that URL.

It ends the action list, so actions after it don't run.

Unlike Download File, this response can be cached when the API has Cache Response turned on. The other parameters control when the cached response is thrown away.

Typical Use Cases

• Serve a generated file, such as a daily report or feed, from a fixed API URL
• Serve a file chosen by SQL, for example the latest version of a document, and cache the result
• Keep a cached API response until a file or a cache key changes

Don't use it to

• Rename the file, force a download, or check folder permissions in the action. Use Download File instead.
• Return a file by path. This action only accepts a file ID. Use Download File for paths.
• Return text, HTML or JSON. Use Raw Response or one of the JSON actions instead.

Related Actions

Action Name	Description
Download File	Sends a file's content with a file name, permission checks and a download or preview option.
Raw Response	Returns any text content, with your own status code and headers.
Clear Cache Item	Removes a cache key, which clears cached responses that depend on it.
Generate PDF	Creates a PDF and stores its file ID in a token.

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 Id	The ID of the file to return, for example [FileId]. It must be a whole number after tokens are replaced.	Yes	empty string	Yes
File Dependencies	Files that invalidate the cached response when they change. One per line: a file ID, a full disk path, or a path relative to the portal's home folder, for example Reports/data.csv. The File Id file is always included, so don't add it here. Only used when Cache Response is on.	Yes	empty string	No
Cache Key Dependencies	Cache keys that invalidate the cached response when they're removed. One per line, for example Reports_[Year]. Only used when Cache Response is on.	Yes	empty string	No

How the file is served

The action looks up the file by its ID and transfers the request to the file's URL on the server. The caller doesn't see a redirect. The response is whatever the site returns for that URL, including its status code, content type and headers.

• For files in a standard folder, that's the file's normal URL.
• For files in a secure or database folder, DNN's URL for the file is a LinkClick.aspx link, and DNN's own handling of that link applies.

If no file has that ID, including when File Id isn't a whole number, the caller gets a 404 Not Found with an empty body.

The action itself doesn't check folder permissions and doesn't limit the file to the current portal.

Response caching

When the API has Cache Response turned on, the first call runs the actions and caches the File Response for the same input parameter values. Later calls with the same inputs skip the actions and serve the file again. The cached response is removed when:

• The cache time set on the API expires
• The File Id file changes on disk
• Any file in File Dependencies changes
• Any key in Cache Key Dependencies is removed, for example with Clear Cache Item

The file itself is always served fresh. Caching only skips running the actions that choose it.

When Cache Response is off, File Dependencies and Cache Key Dependencies have no effect.

Considerations

• Cache is shared. A cached response depends only on the input parameter values, not on who's calling. Don't cache an API that picks a different file for each user unless the user is one of the inputs.
• Validate the input. If File Id comes from the request, any caller can ask for any file ID. Check it first, for example with a Run SQL Query and a condition on this action, or use Download File with its permission checks.
• Unresolved dependencies are skipped. Lines in File Dependencies that don't match a file on disk or in the portal are ignored without an error.
• 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. Serve a file by ID

This action returns the file whose ID is in the FileId input parameter. It runs only when FileId isn't empty.

{
    "Title": "File Response",
    "ActionType": "FileResponse",
    "Description": "Return the requested file",
    "Condition": "[FileId] != \"\"",
    "Parameters": {
        "FileId": "[FileId]",
        "FileDependencies": "",
        "CacheKeyDependencies": ""
    }
}

2. Serve a cached report until the data changes

The API has Cache Response turned on. This action returns the report whose ID is in the ReportFileId token, for example from a previous Run SQL Query. The cached response is cleared when Reports/data.csv changes, or when the Reports_[Year] cache key is removed.

{
    "Title": "File Response",
    "ActionType": "FileResponse",
    "Description": "Return the yearly report",
    "Parameters": {
        "FileId": "[ReportFileId]",
        "FileDependencies": "Reports/data.csv",
        "CacheKeyDependencies": "Reports_[Year]"
    }
}

Revised 09/27/2026