Login

addTag(path, tag) Last updated: 10. Aug 2026

API only function

Adds a tag to a document without touching the tags that are already there.

Only the missing tag is written, so two scripts tagging the same document at the same time cannot delete each other's tags — which a read-modify-write of the whole tag list would.

See also: removeTag getTags Tags are stored as search words Path traversal

Parameters

Name Type Description
path string

Absolute path to the file, from the site root.
tag string

The tag to add. It is normalized before it is stored, exactly as the tag field in the editor is: lower cased and split into words. "Annual report" therefore stores two tags, and a word of a single character is dropped entirely. Read the returned list to see what was actually stored.

Returns

An array of strings — the document's tags after the operation, in the form they are actually stored. The whole list is returned rather than a boolean precisely because normalization can change what you passed in, so you can see the result without a second getTags call.

Adding a tag the document already has is not an error. The end state is the one you asked for and the list comes back unchanged, so the call is safe to repeat.

Throws an error if the path or the tag is empty, if the path contains .. or a backslash, if the file is not found, or if you do not have edit access to the document. Access control is the same as in the editor — the JS API is not a cheaper way in.

Example

Code example (JS)

JS is normal JavaScript either running in the browser or on the Docly™ server. 
// Add a tag. The return value is the document's tags after the call.
var tags = docly.addTag("Invoices/Invoice 1001.docly", "Paid");
// -> ["invoice", "2024", "paid"]

// Casing does not matter - tags are always stored in lower case.
docly.addTag("Invoices/Invoice 1001.docly", "PAID");
// -> unchanged, the tag is already there

// A tag of several words is split into one tag per word,
// so a single call can store more than one tag.
docly.addTag("Reports/Report 2024.docly", "Annual report");
// -> ["annual", "report"]

// Words of one character are dropped, so this stores nothing at all.
// The returned list is the only thing that tells you.
var result = docly.addTag("Reports/Report 2024.docly", "a");
// -> ["annual", "report"] - unchanged

// Only the tags you name are touched, so this is safe to run
// from several scripts against the same document at the same time.
for (var file of docly.listFiles("/Invoices"))
{
    docly.addTag("/Invoices/" + file.Name, "archived");
}