Skip to content
Try for free
On this page

Integrations

File

Read, search, get content, fetch, write, append, compress, decompress, and manage sharing for files

Use the File block to read or extract workspace files, search their contents, fetch files from URLs with custom headers, write or append content, create or extract ZIP archives, and manage share links with public, password, email, or SSO access. Additional actions apply precise text edits, move files, and list, create, move, delete, or restore folders.

Folder selection is optional and supports multiple folders. Choose folders from the workspace, or switch to advanced mode and provide comma-separated paths or a value from an earlier block. Without a folder selection, Search spans the workspace and file pickers are unscoped. Selected folders are expanded when the workflow runs, so newly added files are included.

Use the block

Read workspace file objects, search indexed text across the workspace or selected folder scopes, extract the text content of files, fetch and parse files from URLs with optional headers, write new workspace files, append content to existing files, compress files into a .zip archive, extract a .zip archive into the workspace, or manage the public share link for a file.

Actions

File Read

Read workspace file objects from selected files, canonical workspace file IDs, or one or more workspace folders.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileIdstringNoCanonical workspace file ID, or an array of canonical workspace file IDs.
fileInputfileNoSelected workspace file object.
folderPathsarrayNoFolders whose files are included, as canonical percent-encoded paths, e.g. ["/Reports/Q3%20Results"]. Nested folders are included by default, and the folders are read at run time, so a file added later is picked up.
includeSubfoldersbooleanNoWhether nested folders are read too. Defaults to true; set false to take only the folders’ direct files.

Output

ParameterTypeDescription
filesfile[]Workspace file objects

File Get Content

Extract workspace file text using the same parser mode as File Search. Use the returned fileId and offset/limit to read the matching line and surrounding context. For documents and spreadsheets, line numbers refer to extracted text, not page numbers or worksheet row numbers.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileIdstringNoCanonical workspace file ID, or an array of canonical workspace file IDs.
fileInputfileNoSelected workspace file object, or an array of file objects.
folderPathsarrayNoFolders whose files are included, as canonical percent-encoded paths, e.g. ["/Reports/Q3%20Results"]. Nested folders are included by default, and the folders are read at run time, so a file added later is picked up.
includeSubfoldersbooleanNoWhether nested folders are read too. Defaults to true; set false to take only the folders’ direct files.
offsetnumberNoFirst line to return, 1-based. Applied to each selected file separately, so a multi-file selection returns the same window of each. Absent starts at the first line.
limitnumberNoHow many lines to return from the offset. Absent reads to the end. Use this to read part of a long file instead of all of it; the response reports the total line count alongside the window.

Output

ParameterTypeDescription
contentsarrayArray of file text contents, one entry per file in input order
lineRangesarrayPresent when a line range was requested: one entry per file, in the same order, with offset, lineCount, and totalLines

File Search

Search the indexed text of active workspace files for lines matching a query, and return each matching line once with its file ID and line number. By default the query is a regular expression; in exact mode it is matched verbatim and metacharacters are literal. Coverage is what the index currently holds. A term that is not found is only authoritative when "complete" is true AND "indexStatus" reports no skipped files; otherwise it is unknown rather than absent, so re-check before creating something on the assumption it is missing. Narrow the search with folderPaths to confine it to one or more folder trees, which also narrows "indexStatus" to those trees.

Inputs and outputs

Input

ParameterTypeRequiredDescription
querystringYesA regular expression matched against each line, 3-512 characters. Supports "." "*" "+" "?" "{n,m}" and their lazy forms, character classes such as "[a-z]" and "[^0-9]", the classes \d \w \s and \D \W \S, alternation "|", groups "(...)" and "(?:...)", the anchors "^" and "$", and the word boundary \b. Lookahead, lookbehind, backreferences, named groups, inline flags such as "(?i)", \p{...} and POSIX "[[:alpha:]]" classes are not supported, and a pattern cannot span a line break. The pattern must contain at least 3 consecutive literal characters that every match will include — write "error \d+" rather than "\w+ \d+". Escape any metacharacter you mean literally. Matching is case-insensitive until the pattern contains an uppercase letter you are searching for; uppercase inside an escape or a character class, such as \D or [A-Z], does not make it case-sensitive. When the workflow builder sets Match to exact instead, the query is matched verbatim and no metacharacter needs escaping.
modestringNoHow the query is read, chosen by the workflow builder: "regex" (default) as a regular expression, or "exact" as verbatim text.
maxResultsnumberNoHard result cap configured by the workflow builder (1-200, default 50).
folderPathsarrayNoFolders the search is confined to, as canonical percent-encoded paths, e.g. ["/memory/user-a"]. Absent searches the whole workspace. Scoping also narrows the reported index coverage, so "complete" describes the folders searched.
includeSubfoldersbooleanNoWhether the scope descends into nested folders. Defaults to true; set false to search only the folders’ direct files.

Output

ParameterTypeDescription
resultsarrayMatching logical lines with their workspace file ID and 1-based line number.
↳ fileIdstringCanonical workspace file ID.
↳ lineNumbernumber1-based logical line number.
↳ textstringMatching line or bounded match-centered preview.
countnumberNumber of returned matching lines.
truncatedbooleanWhether more matching lines exist beyond the configured hard cap.
completebooleanWhether indexing has no pending or failed current revisions; excluded files are reported separately.
indexStatusobjectCurrent workspace search-index coverage by file status.
↳ readyFilesnumberFiles whose entire current extracted text is searchable.
↳ pendingFilesnumberFiles still waiting to be indexed.
↳ failedFilesnumberFiles whose current indexing attempt failed.
↳ skippedFilesnumberFiles excluded in full because they are oversized, unsupported, or cannot be completely extracted.
↳ partialFilesnumberAlways zero; retained for compatibility. Files are never partially indexed.

File Fetch

Fetch and parse a file from a URL with optional custom headers.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileUrlstringYesURL of the file to fetch and parse.
headersobjectNoHTTP headers to include when fetching URL-based files.

Output

ParameterTypeDescription
filesfile[]Fetched files as UserFile objects
combinedContentstringCombined content of all fetched files

File Write

Create a new workspace file, either from text content or from an existing file. If a file with the same name already exists, a numeric suffix is added (e.g., "data (1).csv") unless overwrite is enabled.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileNamestringNoFile name (e.g., "data.csv"). Required when writing text; optional when storing a file, which keeps its own name unless this overrides it. If the name already exists, a numeric suffix is added automatically unless overwrite is enabled.
folderPathstringNoFolder to create the file in. Omit for the workspace root. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".
contentstringNoThe text content to write to the file. Provide exactly one of content or fileInput.
fileInputfileNoAn existing file to store in the workspace, such as one produced by an earlier tool. Use this for anything that is not text — PDFs, images, audio, archives. Provide exactly one of content or fileInput.
contentTypestringNoMIME type for new files (e.g., "text/plain"). Auto-detected from the file extension, or taken from the stored file, if omitted.
overwritebooleanNoReplace the contents of an existing file at the exact target path (folder and name) instead of creating a suffixed copy. Creates the file when that path does not exist yet.
expectedRevisionstringNoRefuse the write unless the file still holds the content this revision names, as returned by Get File or an earlier write. Use it so an edit computed from what you read cannot overwrite someone else’s change.

Output

ParameterTypeDescription
idstringFile ID
namestringFile name
sizenumberFile size in bytes
urlstringURL to access the file
versionnumberVersion number of the content this write recorded
revisionstringOpaque token for the content this write produced. Pass it back as expectedRevision to make a later write conditional on nothing having changed since.

File Append

Append content to an existing workspace file. The file must already exist. Content is added to the end of the file.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileNamestringYesName of an existing workspace file to append to.
folderPathstringNoSingle folder in which to resolve the file name. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/". Use folderPaths for multiple folders; do not provide both fields.
folderPathsarrayNoFolders to search for the named file. The name must resolve to exactly one file across the selected scopes. Do not provide folderPath as well.
includeSubfoldersbooleanNoWhether the folder scope includes nested folders. Defaults to true; set false to target only files directly in the folder.
contentstringYesThe text content to append to the file.

Output

ParameterTypeDescription
idstringFile ID
namestringFile name
sizenumberFile size in bytes
urlstringURL to access the file
versionnumberVersion number of the content this write recorded
revisionstringOpaque token for the content this write produced. Pass it back as expectedRevision to make a later write conditional on nothing having changed since.

Apply File Edit

Apply one precise edit to an existing text file without rewriting it. Use search_replace for verbatim replacement, optionally with replaceAll. Use replace_between, insert_after, or delete_between for complete trimmed-line anchors that stay stable when line numbers move. Folder scope can disambiguate a name or constrain a file ID.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileNamestringYesName or ID of the workspace file to edit.
folderPathstringNoSingle folder in which to resolve the file name or validate the file ID. Canonical folder path, percent-encoded, e.g. "/memory/user-a/people". The workspace root is "/". Use folderPaths for multiple folders; do not provide both fields.
folderPathsarrayNoFolders to search for the named file or validate the file ID against. The name must resolve to exactly one file across the selected scopes. Do not provide folderPath as well.
includeSubfoldersbooleanNoWhether selected folders are searched recursively. Defaults to true; false matches only their direct contents.
modestringYesEdit type: search_replace, replace_between, insert_after, or delete_between.
searchstringNoFor search_replace, the exact text to replace, including whitespace and line breaks. It must be unique unless replaceAll is true.
contentstringNoReplacement or inserted text. Pass an empty string to delete a search match or clear the text between anchors. Omit only for delete_between.
replaceAllbooleanNoFor search_replace, replace every non-overlapping match. Defaults to false, which refuses an ambiguous match.
beforeAnchorstringNoFor replace_between, the complete line before the content to replace. Leading and trailing whitespace is ignored.
afterAnchorstringNoFor replace_between, the complete line after the content to replace. The anchor lines remain in the file.
anchorstringNoFor insert_after, the complete line after which content is inserted.
startAnchorstringNoFor delete_between, the complete first line to delete. The start anchor is removed.
endAnchorstringNoFor delete_between, the complete ending boundary line. The end anchor remains in the file.
occurrencenumberNoFor anchored edits, which start or insert anchor match to use, starting at 1. Defaults to 1. The end anchor is the first match after it.
expectedRevisionstringNoRefuse the edit unless the file still holds the content this revision names, as returned by Get File or an earlier write. Use it so an edit computed from what you read cannot overwrite someone else’s change.

Output

ParameterTypeDescription
idstringFile ID
namestringFile name
sizenumberFile size in bytes
lineCountnumberLines in the file after the edit
versionnumberVersion number of the content this edit recorded
revisionstringOpaque token for the content this edit produced. Pass it back as expectedRevision to make a later write conditional on nothing having changed since.

File Compress

Compress one or more workspace files into a single .zip archive stored in the workspace, for bundling files to download, transfer, or store. Preserves the workspace folder structure of the selected files.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileIdstringNoCanonical workspace file ID, or an array of canonical workspace file IDs.
fileInputfileNoSelected workspace file object, or an array of file objects.
folderPathsarrayNoFolders whose files are included, as canonical percent-encoded paths, e.g. ["/Reports/Q3%20Results"]. Nested folders are included by default, and the folders are read at run time, so a file added later is picked up.
includeSubfoldersbooleanNoWhether nested folders are read too. Defaults to true; set false to take only the folders’ direct files.
archiveNamestringNoName for the .zip archive (e.g., "documents.zip"). Defaults to the source file name when compressing a single file, otherwise "archive.zip".

Output

ParameterTypeDescription
idstringCompressed archive file ID
namestringCompressed archive file name
sizenumberCompressed archive size in bytes
urlstringURL to access the compressed archive
filesfile[]Compressed archive file object, as a single-item array

File Decompress

Extract the contents of a .zip archive into the workspace, preserving the archive folder structure.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileIdstringNoCanonical workspace file ID of the .zip archive to extract.
fileInputfileNoSelected .zip archive file object.

Output

ParameterTypeDescription
filesfile[]Extracted workspace file objects

Manage Sharing

Enable or disable the public share link for a workspace file, and set its access mode (public, password, email, or SSO). Idempotent: the public link stays stable across changes.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileIdstringNoCanonical ID of the workspace file to update sharing for.
fileInputfileNoSelected workspace file object (from the file picker).
isActivebooleanYesWhether the public link is enabled. Set to false to make the file private.
authTypestringNoAccess mode for the link: "public", "password", "email", or "sso". Defaults to "public".
passwordstringNoPassword to protect the link. Required when authType is "password".
allowedEmailsarrayNoAllowed emails or "@domain" patterns. Required when authType is "email" or "sso".

Output

ParameterTypeDescription
urlstringPublic share URL for the file
isActivebooleanWhether the public link is enabled
authTypestringAccess mode: public, password, email, or sso
hasPasswordbooleanWhether the share is password-protected
allowedEmailsarrayAllowed emails/domains for email or SSO access

List Files and Folders

List what is inside a workspace folder: its subfolders and its files together. Lists direct children by default; set Recursive to walk the whole subtree.

Inputs and outputs

Input

ParameterTypeRequiredDescription
pathstringNoFolder to list. Omit to list from the workspace root. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".
recursivebooleanNoList everything beneath the path rather than only its direct children. Each entry carries its depth below the listed folder.
depthnumberNoDeepest level to include when recursive, counted from the listed folder. 1 is direct children.
searchstringNoCase-insensitive substring match against an entry name. Filters the result, so a deep match is still reported even when its parent folders do not match.
limitnumberNoMost entries to return, 200 by default. A listing cut short comes back with truncated set.

Output

ParameterTypeDescription
pathstringThe folder that was listed.
entriesarrayWhat the folder holds. Each entry has kind "folder" or "file", a name, and its depth below the listed folder. A folder carries its own canonical path; a file carries its id, size, type, and the canonical path of the folder holding it.
truncatedbooleanTrue when the limit cut the listing short, so more entries exist.

Create File Folder

Create a workspace file folder at a path. Parent folders are created as needed. Fails if a folder already exists at the path.

Inputs and outputs

Input

ParameterTypeRequiredDescription
pathstringYesPath of the folder to create. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".

Output

ParameterTypeDescription
folderobjectThe created folder, with its name, canonical path, parent path, and timestamps.

Move File Folder

Move or rename a workspace file folder by giving its full destination path. Everything inside the folder moves with it.

Inputs and outputs

Input

ParameterTypeRequiredDescription
pathstringYesFolder to move. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".
destinationPathstringYesFull path the folder should have afterwards. Renaming is a destination whose parent is unchanged. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".

Output

ParameterTypeDescription
folderobjectThe folder at its new path.
previousPathstringThe path the folder had before the move.

Delete File Folder

Delete a workspace file folder. It moves to Recently deleted and can be brought back with Restore File Folder. Deleting a folder that still has contents requires the recursive option.

Inputs and outputs

Input

ParameterTypeRequiredDescription
pathstringYesFolder to delete. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".
recursivebooleanNoAlso delete the folder’s nested folders and files. Without it, deleting a non-empty folder fails.

Output

ParameterTypeDescription
pathstringThe folder that was deleted.
deletedbooleanAlways true when the operation succeeded.
deletedItemsobjectCounts of the folders and files deleted alongside it.

Restore File Folder

Restore a deleted workspace file folder and its contents from Recently deleted. Addressed by folder ID, because a deleted folder has no live path.

Inputs and outputs

Input

ParameterTypeRequiredDescription
folderIdstringYesID of the deleted folder to restore.

Output

ParameterTypeDescription
folderobjectThe restored folder at its live path.
restoredItemsobjectCounts of the folders and files restored alongside it.

Move File

Move an existing workspace file into a folder. Moves the file itself; use Move File Folder to relocate a whole folder.

Inputs and outputs

Input

ParameterTypeRequiredDescription
fileIdstringYesCanonical workspace file ID of the file to move.
folderPathstringNoDestination folder. Omit to move the file to the workspace root. Canonical folder path, percent-encoded, e.g. "/Reports/Q3%20Results". The workspace root is "/".

Output

ParameterTypeDescription
fileIdstringThe file that was moved.
folderPathstringThe folder the file now lives in.

Search coverage and limits

Search indexes the complete extracted text of each eligible file. The source file and its extracted UTF-8 text must each be at most 25 MiB (26,214,400 bytes). Oversized files, unsupported binary formats, and documents that cannot be completely extracted within parser safety limits are excluded as whole files and counted in skippedFiles. Search never indexes only the first rows, lines, or characters. CSV search preserves decoded source text; spreadsheet search includes populated cells beyond the preview limits. Image-only documents require searchable text; search does not perform OCR.

Existing parser safeguards also apply to complete extraction. PDFs allow at most 10,000 pages, 20 MiB of extracted text, 250,000 characters on one page, and 60 seconds of extraction. Office archives allow at most 150 MiB expanded in total, 64 MiB for one archive entry, and 10,000 entries; malformed archives and excessive compression ratios are rejected. Hitting any of these limits excludes the whole file from search.

Updates are indexed asynchronously. pendingFiles and failedFiles indicate revisions that are not yet searchable; a new revision becomes searchable only when its full index is ready. An empty result proves absence only within the searched scope when complete is true and skippedFiles is zero.

Regex is evaluated against complete logical lines, including long lines, and cannot span line breaks. Returned lines may use a shortened preview. The result limit (up to 200 lines) and a 10-second query deadline limit an individual request, not the amount of text indexed. An expensive query fails explicitly instead of returning an apparently complete subset; narrow its literal text or folder scope and retry.

Search returns one result per matching logical line with fileId, 1-based lineNumber, and text (a bounded preview for long lines). An Agent can use Search to locate content, then Get Content with the returned fileId, offset near lineNumber, and a small limit to read surrounding context. These operations use the same complete-text parser mode. Line numbers for documents and spreadsheets refer to extracted text, not page numbers or worksheet row numbers. Re-run search if the file changes between calls.

Was this helpful?
Suggest an edit