Function API only Updated 23 Oct 2026

`saveFile(filePath, data, [options])`

Saves a file to a Docly document according to specified schema. Overwrites if it already exists.

Parameters

filePathstringrequired

Absolute path to where you want to save data, WITHOUT the .docly extension — it is appended for you. Passing "#/queue/item.docly" produces "item.docly.docly".

dataobjectrequired

Data to store, will be converted to JSON and stored.

optionsobjectoptional

Specify any of the following options parameters:

schemastring

Path to the Docly schema to store the file as, WITHOUT the .docly extension — e.g. "#/Schema/Invoice", not "#/Schema/Invoice.docly".
Without a schema a new file is created schemaless, and an existing file is updated in place.
If the file exists with a different schema, it is permanently deleted (not to the recycle bin) and created again with a new guid — embedded files and links to the old guid are lost.

ensurePathbool

If true the folder path will be created if it is missing.
Default is false.

embedBase64bool

If true, base64-encoded content in the data will be extracted and stored as separate embedded attachments, referenced via CID links in the saved document. This reduces document size and improves performance for binary content like images or files. Default is false.

Returns

An object with references to the saved file:

timestamp
id
guid
filename
warning (set when the name looks like a typo, for example a double .docly.docly extension)

Filename may be needed if autogenerated filenames are used.

Writing to #/API/ and names ending in .hash or .js are refused. For schemas without "Allow unsafe data", the content is scanned and unsafe content is blocked.

Example

Normal JavaScript, running in the browser or on the Docly™ server.

export default () => {
    // Note: both paths are extensionless. saveFile appends .docly itself.
    let result = docly.saveFile("#/queue/item-001", { Name: "Ada", Message: "Hello" }, {
        schema: "#/Schema/Feedback",   // NOT "#/Schema/Feedback.docly"
        ensurePath: true
    });
    
    return result;   // { timestamp, guid, filename }
}