Mattering Automations Filestack integration
Connect Filestack to Mattering Automations: ingest files by URL, read metadata, sign and run transformation chains, convert and screenshot and zip, run eight Intelligence tasks, and drive Developer Portal Workflows as workflow steps, authenticated with an API key and an app secret that signs each request.
The Mattering Automations Filestack integration puts Filestack on your automation canvas: ingest a file by URL, read its metadata, download a small file, overwrite or delete one, build and sign a transformation URL without spending quota, run a transformation chain and store the result, convert formats, capture a web page screenshot, zip files, read image dimensions and PDF structure, run eight Intelligence tasks over an image or a piece of text, and trigger a Developer Portal Workflow and collect its results.
The credential has two fields, and both come from the Filestack Developer Portal: an API key, which is public by design because it appears in CDN URLs, and an app secret, which never leaves the server. Nothing travels in an Authorization header here. Filestack authenticates a request rather than a caller, so each protected call carries a short policy document naming the operation, usually the specific file, and an expiry, plus a signature over that policy keyed by the app secret. Mattering mints both per call. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.
One thing is different here from most integrations, and it is easier to understand up front than to hit later. Filestack's Processing API is a URL grammar rather than a list of endpoints: roughly seventy named tasks written into the path, which COMPOSE, so resize then compress then output is one request. That is why this integration ships three grammar nodes split by what comes back (Filestack: Build Transform URL signs and returns a link without calling anything, Filestack: Transform And Store runs a chain and persists the result, Filestack: Transform To JSON runs a chain whose last task answers with data) plus five typed convenience chains and eight Intelligence nodes, instead of seventy palette entries that could never be chained into one render.
Before you start
- A Filestack account with an app in the Developer Portal, so you can copy an API key and generate an app secret.
- The app secret matters more than it looks. A connection carrying only the API key runs the read half of the File API and the unsigned transformation nodes; it cannot run any Intelligence node, nor Filestack: Overwrite File, nor Filestack: Delete File, nor read EXIF metadata, because Filestack requires security on all of those.
- A file to work with, or a publicly reachable URL to ingest one from. Filestack fetches URLs server-side, so no file bytes ever travel through the canvas.
- A plan that covers what you intend to run. Filestack meters transformations per plan rather than publishing a numeric request rate limit for these surfaces, and documents several tasks as premium or plan restricted, including PDF creation, document-to-images and the enhancement marketplace tasks. Filestack's documentation describes capabilities rather than which plan carries them, so confirm your own plan on Filestack's pricing pages before designing a workflow around the Intelligence nodes.
- A place to keep file handles. Filestack documents no endpoint that lists an account's files, so nothing in this integration can look a handle up for you after the fact.
- A Mattering workspace with access to the Automations app.
Get a Filestack API key and app secret
Filestack does not accept a stored credential on the wire. It accepts a signed request, so this integration needs two values rather than one: the API key, which identifies the app and travels in the URL, and the app secret, which stays on the server and signs a small policy document per call. Both live in the Developer Portal.
Connect Filestack to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a Filestack section should list the read and action nodes. Drop Filestack: Get Image Size onto the canvas, point its source at any public image URL, and run a test step. It is the cheapest read in the processing engine, it returns two integers, and it exercises the same API key placement and signing path that everything else on the processing host uses.
Now prove the other half, because the probe cannot. Ingest something with Filestack: Store File From URL, then take the LAST PATH SEGMENT of data.url as the handle and run Filestack: Get File Metadata with it. That is the only way to confirm the File API host, which uses a different parameter placement from the processing host. Note what you learn while you are here: the File API response carries url, size, type, filename and key, and no handle field at all, which is why every node that takes a handle says in its own description where the value comes from. Everything in this verify path except the ingest is read-only, so it cannot reach either destructive node and is safe to re-run whenever you rotate the secret.
Node reference
23 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 15
Filestack: Analyze Image Sentiment
filestack_analyze_image_sentiment
Score the emotions on faces in an image across eight categories (HAPPY, SAD, ANGRY, SURPRISED, CONFUSED, CALM, FEAR, DISGUSTED) as percentages that sum to roughly 100. AN IMAGE WITH NO DETECTABLE FACE RETURNS AN EMPTY emotions OBJECT rather than an error, so branch on whether the object is empty before reading a score out of it. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Analyze Text Sentiment
filestack_analyze_text_sentiment
Classify a piece of TEXT as Positive, Negative, Neutral or Mixed, returned as probabilities from 0 to 1. THE ONLY NODE IN THIS CONNECTOR THAT TAKES NO FILE: the text is passed inline, so it pairs naturally with Filestack: Extract Text With OCR to score a scanned document, or with any upstream node that produced text. Note the scores here are 0-to-1 decimals, unlike the 0-to-100 scores tagging returns. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Build Transform URL
filestack_build_transform_url
Build and SIGN a Filestack CDN URL for a transformation chain, and return it. THIS NODE MAKES NO API CALL: nothing is fetched, nothing is stored, no transformation quota is spent, and the URL is not rendered until somebody opens it. That is what makes it the node most workflows actually want. A transformed image is usually wanted as a LINK - in an email, an img tag, a Slack message, a webhook body - and a link costs nothing to mint. The URL carries a security policy that EXPIRES, so it is a time-limited share rather than a permanent public link. Leave tasks empty to sign a plain delivery URL for the file as stored. If your account has security disabled the URL is still correct, just unsigned.
Filestack: Caption Image
filestack_caption_image
Generate a one-line natural-language description of an image, returned as data.caption. Useful for alt text, for a searchable summary alongside the file, or as the input to a downstream language model. Unlike tagging, this returns prose rather than scored labels. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Check Image Safe For Work
filestack_check_sfw
Classify an image as safe for work or not, returning a single boolean in data.sfw. The moderation gate to put in front of anything user-uploaded before it is published or shared. It is a classifier, not a guarantee: treat a false as a definite hold and a true as a probable pass, and keep a human path for appeals. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Detect Document In Image
filestack_detect_document
Find a document inside a photograph - a receipt on a desk, a form held at an angle - and return where it is. With coords on (the default here) you get the bounding rectangle as x, y, width and height, which is what a workflow can branch on. With coords off Filestack instead returns a CORRECTED image of just the document, and the response then carries url, mimetype and size rather than coordinates. THE INPUT IS CAPPED AT 2000 BY 2000 PIXELS: chain a resize in front of it for larger photos, and check the dimensions first with Filestack: Get Image Size. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Detect Faces
filestack_detect_faces
Find faces in an image and return one box per face as x, y, width and height in pixels. THE RESPONSE IS A TOP-LEVEL JSON ARRAY, which nothing else in this connector returns, so read it as data[0].x rather than data.faces[0].x, and read its LENGTH to count faces. This node always asks for the exported coordinates rather than the annotated image, because file bytes are never a node output; to actually redact faces, run Filestack: Transform And Store with a blur_faces or pixelate_faces task, or mint a URL for one with Filestack: Build Transform URL.
Filestack: Download File
filestack_download_file
Read a stored file's CONTENT back into the workflow. Meant for small text assets: a JSON blob, a CSV, a rendered template. THE BODY IS CAPPED AT 256 KB of raw bytes. Content that decodes as UTF-8 comes back as text in `content` with `encoding` set to utf-8; anything else comes back base64 in the same field with `encoding` set to base64. `size` is always the TRUE size and `truncated` says whether you got all of it, so a clipped read is never mistaken for a whole file. For anything larger, or for handing a file to a person or another system, use Filestack: Build Transform URL to mint a signed, time-limited link instead of moving the bytes.
Filestack: Extract Text With OCR
filestack_ocr
Read printed and handwritten text out of an image or document. Returns the whole extracted text as one string in data.text, plus a hierarchy of text areas, lines and words each with a four-point bounding box, and text_area_percentage saying how much of the image is text. Use data.text for content and the bounding boxes for layout-aware work such as pulling a field out of a form. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Get File Metadata
filestack_get_file_metadata
Read a stored file's metadata without downloading it: size, MIME type, filename, upload time, storage location, container and path, whether it is writeable, and optionally its checksums. Every field is opt-in: ask only for what you need and Filestack returns only that. The cheapest way to confirm a handle still exists. EXIF IS DIFFERENT from every other field here: a security policy allows all calls EXCEPT exif by default, so turning exif on makes this node ask for the exif call explicitly, and that fails on a connection with no app secret.
Filestack: Get Image Size
filestack_get_image_size
Return an image's pixel dimensions. The cheapest read in the processing engine, and the one to branch on before deciding how to resize, or before sending an image to Filestack: Detect Document, which rejects anything over 2000 by 2000.
Filestack: Get PDF Info
filestack_get_pdf_info
Read a PDF's structural metadata without converting it: page count, PDF version, creation date, and whether the document is encrypted or password protected. Branch on pages before splitting a document, or on encrypted before sending it to conversion, which fails on protected files.
Filestack: Get Workflow Status
filestack_get_workflow_status
Poll a workflow job and, once it has finished, read its results. status moves from Started to Finished. THE RESULTS ARE KEYED BY TASK NAME PLUS A TIMESTAMP (results.tags_1571950225779.data.tags), so the key is different on every workflow and a consumer must iterate over data.results rather than address a fixed path. ttl is how many seconds the results are retained - 172800, two days, in Filestack's own example - after which polling returns nothing, so collect what you need inside that window. A webhook is the more reliable way to receive results; this node exists for workflows without one. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Tag Image
filestack_tag_image
Describe what is in an image as a set of tags with confidence scores from 0 to 100, under data.tags.auto. data.tags.user is reserved for user-supplied tags and comes back null. Good for auto-categorising an upload, routing it to a folder, or gating a workflow on whether a concept was detected above a threshold. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Transform To JSON
filestack_transform_json
Run a transformation chain whose LAST task returns DATA rather than a file, and return that data. This is the connector's escape hatch onto the whole Processing API: any task Filestack documents is reachable here, including ones with no typed node (video_convert and video_status, pdfcreate, doc_to_images, ascii, and anything Filestack adds later). If the chain returns a FILE rather than JSON, this node says so and tells you to use Filestack: Transform And Store or Filestack: Build Transform URL instead - file bytes are never a node output. Chains that end in imagesize, pdfinfo, ocr, tags, sfw, caption, image_sentiment, doc_detection or detect_faces with export:true all return JSON, and most of those have a typed node of their own with proper config fields.
Action nodes 8
Filestack: Capture Web Page Screenshot
filestack_capture_screenshot
Render a web page and store the screenshot as a file. Wraps Filestack's urlscreenshot task with a store task appended, so the response names the new image (handle = the last path segment of data.url) rather than returning bytes. Useful for archiving a page as evidence, snapshotting a dashboard on a schedule, or building visual diffs. The page must be publicly reachable; a login-gated page renders as whatever an anonymous visitor sees. If your account has a domain whitelist enabled, the target must be on it.
Filestack: Convert File Format
filestack_convert_file
Convert a document or image to another format and store the result: office documents to PDF, PDF pages to images, images between jpg, png and webp. Wraps Filestack's output task and appends a store task, so the response names the NEW file (its handle is the last path segment of data.url) rather than returning bytes. The source is untouched. Converting a multi-page document to an image format returns one page: set page to choose which. Document conversion is the heaviest thing in the processing engine and large files can take a while.
Filestack: Delete File
filestack_delete_file
DESTRUCTIVE and IRREVERSIBLE: delete a file. Filestack has no trash and no versions, so the file, its handle and every URL and embed built on that handle stop working immediately, and nothing can bring any of it back - re-uploading the same bytes produces a DIFFERENT handle, so existing links stay broken. Set skip_storage to remove the file from Filestack while LEAVING the underlying object in your own storage container, which is the only partially recoverable form of this call and only if you configured your own storage. THIS ENDPOINT ALWAYS REQUIRES SECURITY. Filestack documents no response body: success is HTTP 200 with an empty body, so data comes back as {}.
Filestack: Overwrite File
filestack_overwrite_file
DESTRUCTIVE: replace the CONTENT of an existing file, keeping the same handle. Filestack has no versioning and no trash, so THE PREVIOUS CONTENT IS GONE the moment this succeeds: there is no earlier version to list, no undo, and nothing to restore from. The handle, and therefore every URL and every embed pointing at it, keeps working and silently starts serving the new bytes - which is the whole point of the node and also the reason a wrong handle here is worse than a wrong handle almost anywhere else. Note the CDN caches each unique URL for 30 days, so readers may keep seeing the OLD content until the cache expires or the URL changes. THIS ENDPOINT ALWAYS REQUIRES SECURITY: it fails on a connection with no app secret, regardless of the account's security setting.
Filestack: Run Workflow
filestack_run_workflow
Run a Workflow you built in the Filestack Developer Portal against a file. ASYNCHRONOUS: this returns immediately with status Started and a jobid, and the actual results arrive either at your configured webhook or from Filestack: Get Workflow Status. This is also the ONLY way to reach Filestack's Workflows-only intelligence tasks - VIRUS DETECTION and PHISHING DETECTION are not Processing API tasks and have no node of their own, so build a workflow containing them and run it here. Whether the run changes anything depends entirely on what the workflow does: a tagging workflow is a read, a workflow with a store or delete step is not. REQUIRES SECURITY: this fails on a connection with no app secret.
Filestack: Store File From URL
filestack_store_from_url
Ingest a file into Filestack by URL. FILESTACK FETCHES THE URL SERVER-SIDE, which is why this is the connector's only upload node: raw file bytes cannot travel through a canvas field, so the source has to be something Filestack can reach. The URL must be publicly readable (or reachable without credentials). The response carries the CDN url, size, MIME type, filename and storage key; THE NEW HANDLE IS THE LAST PATH SEGMENT OF data.url, which every other node in this connector wants. Reversible with Filestack: Delete File.
Filestack: Transform And Store
filestack_transform_store
RUN a transformation chain and PERSIST the result as a new file. This node appends Filestack's store task to whatever chain you give it, so the response is JSON naming the new object rather than the transformed bytes - which is how a transformation is executed without file content ever crossing a node boundary. THE NEW HANDLE IS THE LAST PATH SEGMENT OF data.url. The source file is untouched, so this is reversible by deleting the result. Every run that is not already cached spends transformation quota. Use Filestack: Build Transform URL instead when you only need a link, and Filestack: Transform To JSON when the chain's last task returns data rather than a file.
Filestack: Zip Files
filestack_zip_files
Bundle several files into one zip archive and store it. Wraps Filestack's zip task with a store task appended, so the response names the new archive (handle = the last path segment of data.url). The sources may be Filestack handles or public URLs, mixed freely. Nothing is removed: the originals are untouched and the archive is a new file. Pair it with Filestack: Build Transform URL to hand the archive out as a time-limited download link.
Using the integration
On the automation canvas
Filestack nodes chain with every other node. An inbound webhook carrying a file URL can run Filestack: Store File From URL, gate the result on Filestack: Check Image Safe For Work, and write the handle, the tags from Filestack: Tag Image and the caption from Filestack: Caption Image into a Mattering database row. A scheduled job can run Filestack: Capture Web Page Screenshot against a page you want a visual record of. One value does most of the wiring, and it is the one Filestack does not name for you: the handle, which is the last path segment of data.url on every node that creates or reads a file.
From AI assistants over MCP
Every node speaks MCP, the open protocol for connecting AI assistants to tools, so Claude, ChatGPT, and Matter, the assistant built into the platform, can drive the same surface. The fifteen read nodes are the comfortable surface to hand an agent: metadata, image size, PDF info, the eight Intelligence tasks, and Filestack: Build Transform URL, which signs a link and calls nothing. Keep Filestack: Overwrite File and Filestack: Delete File behind conditions or approval steps. Filestack publishes an official Claude plugin that exposes Filestack as MCP tools, and it is worth knowing about before you choose: if what you want is an assistant helping you work with Filestack itself inside your editor or client config, use the vendor's server. This integration is the operations side: the same nodes run as canvas steps as well as over MCP, so a check can run on a schedule with nobody present, chain with every other connector in one workflow, and hold the credential once in a shared workspace store rather than in each person's local config.
The transformation grammar, split by what comes back
This is the wrinkle worth ten seconds of attention. Filestack's transformations are tasks written into a URL path, and they compose, so the useful unit is a CHAIN rather than a call. The tasks field on the three grammar nodes takes a structured list, for example a resize with a width and a fit, then a compress, then an output format, which Mattering serializes into Filestack's own path syntax. A raw chain string is accepted too, so a working Filestack URL you already have can be pasted straight in. Which node you pick depends only on what you want back. Filestack: Build Transform URL signs the chain and returns the URL, makes no network call, and spends no transformation quota, which makes it the right node whenever the product is a link. Filestack: Transform And Store appends Filestack's store task, so the chain actually runs and the response names the new file. Filestack: Transform To JSON is for chains whose last task answers with data rather than a file, and it is the escape hatch onto anything Filestack documents that has no dedicated node here, including the asynchronous video and audio tasks, which are ordinary tasks in the same grammar.
Intelligence tasks, and the two scales they answer on
Eight nodes cover the JSON-returning Intelligence surface: Filestack: Extract Text With OCR, Filestack: Tag Image, Filestack: Check Image Safe For Work, Filestack: Caption Image, Filestack: Analyze Image Sentiment, Filestack: Analyze Text Sentiment, Filestack: Detect Document In Image and Filestack: Detect Faces. All eight require security, so they need the app secret on the credential. Three response details save an afternoon. Tag confidences are integers from 0 to 100 while text sentiment probabilities run from 0 to 1, and Filestack calls both scores. Filestack: Analyze Image Sentiment returns an EMPTY emotions object when it finds no face, rather than an error, so branch on emptiness first. And Filestack: Detect Faces answers with a top-level JSON ARRAY, which nothing else here does, so a face box is read as data[0].x and the face count is the array length. That node also forces the export option on, because without it the task returns an annotated image rather than data. To actually redact faces, run Filestack: Transform And Store with a blur or pixelate faces task.
Ingesting, downloading, and where the bytes are not
No file bytes cross a node boundary in either direction, with one capped exception. Filestack: Store File From URL hands Filestack a publicly reachable URL and Filestack fetches it server-side, which is why this is the only ingestion node: a canvas field cannot hold file bytes. Transformations never return transformed bytes either; they return a signed URL or a stored handle. The exception is Filestack: Download File, which reads a stored file's content back into the workflow and is capped at 256 KB of raw bytes. Content that decodes as UTF-8 comes back as text and anything else comes back base64, the reported size is always the TRUE size, and a flag says whether the read was clipped. It is meant for small text assets, a JSON blob or a CSV, not for moving media around.
Workflows, and the two capabilities that live only there
Filestack: Run Workflow runs a Workflow you built in the Filestack Developer Portal against a file and returns immediately with a job id, and Filestack: Get Workflow Status polls it and returns the results once it has finished. This is also the supported route to virus and phishing detection, which Filestack documents as available only inside Workflows and not as Processing API tasks, which is why this integration ships no node for either: such a node would be a URL that fails. Two facts govern reading the output. Results are keyed by task name plus a timestamp, so the key is different on every workflow and a consumer must ITERATE data.results rather than address a fixed path. And results expire on a TTL, so collect them inside the window. Filestack: Run Workflow is classed as an action rather than a read because what a run does is whatever the workflow contains: a tagging workflow reads, and a workflow with a store or a delete step does not.
The two destructive nodes, gated
Filestack: Delete File takes the file, its handle and every URL and embed built on that handle immediately. Filestack keeps no trash and no versions, and re-uploading the same bytes mints a DIFFERENT handle, so links that pointed at the old one stay broken. Filestack: Overwrite File is the subtler harm: the handle survives while the content behind it changes, so everything already pointing at it silently starts serving the new bytes and the previous content is unrecoverable. The pattern for both is the same: put them behind a condition or an approval task rather than a bare trigger, and read the file with Filestack: Get File Metadata first if anything downstream depends on what is there now. One caching consequence is worth knowing before you debug the wrong thing: because Filestack caches each unique URL for up to 30 days, an overwrite can appear to do nothing to anyone holding a cached link long after it succeeded.
Signing, expiry, and what the policy actually allows
Each protected call is signed with a policy that names the operation, pins the specific file where the node addresses exactly one, and carries an expiry, so a leaked URL leaks one file for a few minutes rather than the account. Every node exposes the expiry as a field. The default is short on nodes that sign and immediately use the URL, and longer on Filestack: Build Transform URL, whose whole product is a link somebody opens later. Widen it when a chain is slow or when the link is meant to survive a review cycle. Two operational consequences follow. An expired policy and a wrong secret produce the same status and the same body, so widen the expiry before suspecting the credential. And a re-signed URL is a DIFFERENT URL, so it misses Filestack's cache and re-renders, which is metered: minting new links more often than you need to is a real cost rather than a free retry.
Troubleshooting
Test Connection passes but an Intelligence node fails
A signed call fails and it is not obvious whether the secret or the timing is wrong
A node that fetches an external URL fails on a credential that works everywhere else
Overwriting a file appears to change nothing
A template pointing at data.handle resolves to nothing
A workflow results path never resolves
Detect Document In Image fails on a large photo
Transform To JSON returns an error about a non-JSON response
Analyze Image Sentiment returns nothing useful
Related
The Filestack MCP
What connecting Filestack unlocks for AI agents and automations, with common uses and FAQs.
More guides
All Automations documentation
Every integration guide, plus how connectors, credentials, and workflows fit together.
Filestack is a trademark of its respective owner. Mattering uses platform names to identify the services these integrations connect to; no endorsement or affiliation is implied.