Docly Developers
Function Updated 25 Oct 2026

getFiles(path, [options])

Gets a list of files from folder / optionally recursively from subfolders.

See also getFile listFiles getFolder getFolders GetFiles and Folders - examples List folders (for) getTags addTag getAllTags Path traversal Example: Create custom API functions Example: Example of dynamic sitemap.xml file Example: Request variables and edit links - example

Parameters

pathstringrequired

Path to the folder, from the site root. An empty string means the site root. A path containing .. or a backslash returns null.

optionsobjectoptional
Specify any of the following options parameters:
namestring

Filename wildcard (e.g. ".pdf"), default is ""

depthnumber

Subfolder levels to traverse, default is 0.

modeenum

Detail level: "Full", "Medium" (default), "Min" or "Json". Omitting the parameter — or passing null — gives "Medium".

schemastring

Schema name wildcard, default is "*"

recursiveboolean

Include files from all subfolders. Default false.

searchstring

Search query using the built-in search engine. Only returns files matching the search criteria. Searches filenames, tags, and indexed fields. Accepts search query as string (e.g. "annual report"). Each word is matched as a prefix (rep finds report), every word must match, and only the first 16 words are used.

filterobject | function

Filter items based on their properties. Accepts either:

  1. Object with key-value pairs for exact matching (e.g. { "Status": "active", "Category": "docs" })
  2. Function that receives each file and returns true/false (e.g. x => x.Filesize > 1000 && x.MyProperty == "myValue")
fieldscsv | array | object

Specify fields to retrieve via:

  1. CSV string (e.g. "filename,Filesize")
  2. Array of strings (e.g. ["filename","Filesize"])
  3. Object map for renaming (e.g. {"newName":"filename"})
tagstring

Only return files carrying this tag. The value is normalized exactly as tags are when they are stored, so "Invoice" finds the stored tag invoice. A value of several words requires all of them, and a value that normalizes to nothing (a single character, punctuation only) returns an empty result rather than everything. Filtering happens in the database, not on the returned array — unlike search, which runs the full text search engine, tag is an exact match against the document's tags. See addTag.

tagsbool

Include a Tags array with each file, default false. Use this instead of mode "Full" when tags are all you need — it adds the tag join without the rest of the Full detail level. Not to be confused with tag (string), which filters on a tag instead of returning them.

Returns

An array of file objects.

Folder properties files and index.* files are never included. An unknown folder, or a folder the site's publisher has no website (Visit) access to, gives an empty array. With recursive or depth, files in subfolders the publisher has no website (Visit) access to are left out, and so are files inside # folders below the folder you asked for. Access is that of the user who published the site — the user the site runs as — not of the visitor, so the result is the same for everyone. To tailor a list to the signed-in visitor in an API script, check each item with allowVisit.

Each object is the document's own fields with Docly's file metadata merged in, so your schema's field names appear alongside the ones below. Docly writes its metadata last, so a field of yours that shares a name with one of them is overwritten — the one exception is Title, where your own value wins. Which metadata you get depends on mode.

Always present, from "Min" and up:

Field Description
filename File name, extension trimmed
filepath Path from the site root, with .hash/.html trimmed. null in "Min"
fileschema Schema name, null for a schemaless file
file Always true — lets you tell files from folders in a mixed list
Guid The document's id
CreatedTime When the file was created
LastModified When the file was last changed
Filesize Size in bytes

"Medium" adds — this is the default:

Field Description
folderpath Path to the containing folder, with no trailing slash. null for a file at the site root
Url filepath, URL-encoded
Title The document's own Title if it has one, otherwise the file name
FormName Schema name
DoclyTypeId Document type id
DoclyTimestamp LastModified as ticks — useful as a cache key or change check
opendoc Link that opens the document in the Docly workspace

"Medium" is also where filepath gets a value; in "Min" it is null.

"Full" adds:

Field Description
Tags Array of the document's tags
LastModifiedBy Email of the user who last changed the file

Tags costs a database join, which is why it is not in the default. If tags are all you need, keep "Medium" and pass tags: true instead of stepping up to "Full".

"Json" returns a different, flatter shape — a database record rather than the merged document:

Field Description
Id Internal numeric id
Guid The document's id
Name File name, extension included
Values The document's stored values, as raw JSON
Modified When the file was last changed
Schema Schema name, null for a schemaless file
ModifiedBy Email of the user who last changed the file
Path Always null from getFiles

Use "Json" when you want to pass the values on untouched; the document's fields are inside Values rather than on the object itself.

Example

Mixed HTML (or any text file) with inline JavaScript between hash signs.
#{
    // Get files from folder
    let files = docly.getFiles("/Test files"); 
    
    // Get first item of array
    let first = files[0];
    
    // Convert object to JSON string
    let json = JSON.stringify(first);

    // Format indent and line breaks in JSON
    let pretty = docly.formatJson(json);
    
    // Remove empty lines
    let html = pretty.replace(chr(13), "");
    
}#

<b>Information about first file:</b>
#html#