Docs
Kiwi Flow
Version Current

API reference

File and storage activities

Local files and folders on the worker, and governed file references.

Flow Current 6 min read Updated

Local files and folders on the worker, and governed file references. This page covers 3 activity types.

file#

File. Local file operations on the worker node: read text, read as base64 (for binary/image files), write, append, copy, move, delete, check existence, and get file info

Operations: read, read_base64, write, append, copy, move, delete, exists, info. Set with the operation input.

Input Type Required Description
operation string Yes Operation: read, read_base64, write, append, copy, move, delete, exists, info Allowed values: read, read_base64, write, append, copy, move, delete, exists, info. Default: read.
fileReference string No Use a File Reference activity's output instead of configuring Storage/Area/path separately below — the exact Storage, Area, and filename it built. Can reuse a file_reference node.
storageId string No Use a governed Storage instead of a literal path below — the physical location is configured by an administrator and never exposed to the workflow.
areaId string No Storage Area within the Storage above — the RBAC boundary this operation is authorized against.
relativePath string No Path relative to the Storage Area's root (all operations)
destinationRelativePath string No Destination path relative to the Storage Area's root (copy/move operations) Used when operation is copy, move.
path string Yes Source file path (ignored when a Storage or File Reference is picked above)
content string No Content to write or append (write/append operations) Used when operation is write, append.
destination string Yes Destination path (copy/move operations, ignored when a Storage or File Reference is picked above) Used when operation is copy, move.
encoding string No File encoding (default: UTF-8) Used when operation is read, write, append. Allowed values: UTF-8, ASCII, UTF-16, ISO-8859-1.
overwrite boolean No Overwrite the destination if it already exists (default: false — errors instead of replacing it) Used when operation is write, copy, move.
createDirectories boolean No Create intermediate directories if they do not exist (default: true) Used when operation is write, append.
ignoreIfNotFound boolean No [delete] Do not throw if the file does not exist (default: false) Used when operation is delete.
Output Type Description
output.content string File content as text (read) or as base64-encoded string (read_base64)
output.mimeType string Detected MIME type of the file (read_base64 operation)
output.fileName string File name without directory path (read_base64 operation)
output.sizeBytes number File size in bytes
output.exists boolean Whether the file exists (exists operation)
output.path string Resolved absolute path of the file

Config block example:

json
{
  "inputs": [
    {
      "name": "operation",
      "value": "read_base64"
    },
    {
      "name": "path",
      "value": "/invoices/inv-001.png"
    }
  ]
}

file_reference#

File Reference. Builds a governed reference (Storage + Storage Area + relative path) to a file, from a filename/path template evaluated exactly once when this activity runs. Pass the result to a downstream File/Folder/Excel activity's "File Reference" input instead of configuring Storage/Area/path separately there.

Input Type Required Description
storageId string Yes The registered Storage this file belongs to.
areaId string Yes Storage Area within the Storage above — the RBAC boundary this file reference is authorized against.
template string Yes Filename/relative-path template, evaluated exactly once when this activity executes and then immutable for the rest of this run. Supports the same {{...}} expressions as any other field (workflow inputs, globals, upstream activity output) plus four built-in functions: {date: <format>}, {timestamp}, {random-int: <digits>}, {random-string: <length>}. See the template help for the full syntax.
Output Type Description
output.fileReference object The strongly typed file reference (storageId, areaId, relativePath). Pass this to a downstream activity's "File Reference" input — it must not be reconstructed from separate Storage/Area/filename fields.
output.relativePath string The resolved relative path/filename alone (e.g. for logging or display) — relative to the Storage Area's root, never the physical Storage path.

Config block example:

json
{
  "inputs": [
    {
      "name": "storageId",
      "value": "storage_abc123"
    },
    {
      "name": "areaId",
      "value": "area_def456"
    },
    {
      "name": "template",
      "value": "inv_data_{date: dd_mmm_yyyy}_{timestamp}_{random-int: 5}.csv"
    }
  ]
}

folder#

Folder. Local directory operations on the worker node: create, delete, list, copy, check existence, and get directory info

Operations: create, delete, list, copy, exists, info. Set with the operation input.

Input Type Required Description
operation string Yes Operation: create, delete, list, copy, exists, info Allowed values: create, delete, list, copy, exists, info. Default: list.
fileReference string No Use a File Reference activity's output instead of configuring Storage/Area/path separately below — the exact Storage, Area, and path it built. Can reuse a file_reference node.
storageId string No Use a governed Storage instead of a literal path below — the physical location is configured by an administrator and never exposed to the workflow.
areaId string No Storage Area within the Storage above — the RBAC boundary this operation is authorized against.
relativePath string No Directory path relative to the Storage Area's root (all operations)
destinationRelativePath string No Destination directory path relative to the Storage Area's root (copy operation) Used when operation is copy.
path string Yes Directory path to operate on (ignored when a Storage or File Reference is picked above)
pattern string No Glob pattern to filter files (list operation, e.g. *.png, .pdf). To match more than one extension, combine patterns with ';' in a single value, e.g. .jpg;.jpeg;.png — do not use a separate script activity to filter by extension. Does not filter subdirectory names when recursive is true. Used when operation is list.
recursive boolean No When true, descend into all subdirectories and return matching files from every level (list/delete operations, default: false) Used when operation is list, delete.
includeFiles boolean No Include files in list results (default: true) Used when operation is list.
includeDirectories boolean No Include subdirectories in list results (default: true) Used when operation is list.
destination string Yes Destination directory path (copy operation, ignored when a Storage or File Reference is picked above) Used when operation is copy.
overwrite boolean No Overwrite existing files at the destination (copy operation, default: false) Used when operation is copy.
ignoreIfNotFound boolean No Do not throw if the directory does not exist (delete operation, default: false) Used when operation is delete.
Output Type Description
output.items array List of entries (list operation). Each item has: name, path, relativePath, directory, isDirectory, sizeBytes, modified
output.count number Number of items found
output.created boolean Whether the directory was newly created
output.deleted boolean Whether the directory was deleted
output.filesCopied number Number of files copied (copy operation)

Config block example:

json
{
  "inputs": [
    {
      "name": "operation",
      "value": "list"
    },
    {
      "name": "path",
      "value": "/data"
    },
    {
      "name": "pattern",
      "value": "*.json"
    }
  ]
}