Mattering Automations Shotstack integration
Connect Shotstack to Mattering Automations: save and render templates, submit edits and poll them to done, collect the durable CDN asset, ingest footage from a URL and mint signed upload URLs, authenticated with one API key whose environment is part of the credential.
The Mattering Automations Shotstack integration puts all three Shotstack APIs on your automation canvas. Edit gives you templates, render submissions, the render status poll and media inspection. Serve gives you the CDN-hosted assets a render or a source produced, plus a transfer into hosting. Ingest gives you source files, a server-side fetch from a URL and a signed direct-upload URL. One credential covers all three, and no config panel asks which API a node belongs to, because choosing the node has already chosen it.
The credential is an API key sent in Shotstack's own header, plus one more thing that is easy to skip and expensive to get wrong: the Environment. Shotstack runs a sandbox and a production environment with a SEPARATE key for each, and a key issued for one does not authenticate against the other, so the environment is a property of the key rather than a per-job setting, and it lives on the credential. It defaults to the sandbox, where output is watermarked. Setup takes a few minutes, and this guide walks through each step and ends with the full node reference.
One behaviour governs almost every workflow built here. Renders are ASYNCHRONOUS: Shotstack: Render Video and Shotstack: Render Template return a render id immediately and the file does not exist yet. Shotstack: Get Render Status is the node a workflow polls and branches on, and its status moves from queued through fetching, rendering and saving to done, with any of those able to become failed instead. Only done carries the output URL and only failed carries the error. There is deliberately no wait node in this integration, because a node that blocked for minutes would hold a worker and hide its own timeout policy, while a poll loop built from the platform's scheduling and branching keeps that interval visible and adjustable.
Before you start
- A Shotstack account. Signing up issues an API key for each environment, and a key issued for one does not authenticate against the other.
- A decision about which environment to connect first. The sandbox is the right place to build: output is watermarked so nothing rendered by accident is publishable, and a sandbox render is capped at ten minutes. Shotstack's key documentation states that only AI assets are charged in the sandbox, and its limits documentation notes at least one credit is required to use the sandbox at all.
- An understanding of what a render costs in production. Every submission spends plan credits, generative AI clip types cost extra credits even in the sandbox by Shotstack's own note, and Shotstack documents no way to cancel a queued render, so a mis-triggered render is money spent rather than a mistake undone. Check Shotstack's pricing page for what your plan includes.
- Publicly reachable source files. Every URL Shotstack fetches, whether for Shotstack: Inspect Media File, an ingest, a transfer or a clip inside a timeline, has to be reachable without authentication, so a signed or expiring URL that opens in your browser can still fail server-side.
- A Mattering workspace with access to the Automations app.
Get a Shotstack API key
Shotstack sends the key in its own header rather than as a bearer token, and there is no signature, no account id and no OAuth step. What the credential needs beyond the key is the environment that key belongs to, because Shotstack issues one key per environment and pairing the wrong two produces a 401 rather than a useful error.
Connect Shotstack to Mattering
Verify it works
After connecting, open any automation canvas and check the palette: a Shotstack section should list the read and action nodes. Drop Shotstack: List Templates onto the canvas and run a test step. It needs no parameters, it returns every saved template with its id, name and timestamps, and an empty list is still a pass: it proves the credential rather than the content. It is also the node the template pickers elsewhere read from, so a working list is what makes those fields populate.
Now prove the other two APIs, because the connection test does not. Shotstack is three path prefixes on one host with their own routing and their own rate-limit buckets, so a passing Edit read says nothing about Serve or Ingest. Run Shotstack: List Sources for Ingest, which returns each ingested file with its hosted URL, dimensions, duration, frame rate and ingest status. Then, if you already have a render id or a source id, run Shotstack: Get Assets By Render or Shotstack: Get Assets By Source for Serve. Watch the response shapes while you are here, because they differ by API and it is not something you can guess: Edit wraps its payload in a vendor envelope, so paths read through a response object, while Serve and Ingest use a JSON:API envelope with the payload under a data key and its fields under attributes. Everything in this verify path is read-only, so it cannot reach the three destructive nodes and renders nothing.
Node reference
20 nodes, generated from the connector itself so this reference always matches what ships.
Read and query nodes 10
Shotstack: Get Asset
shotstack_get_asset
Look up one hosted asset by its own id and read its CDN url, filename, region and status. Asset status is ready or deleted. Reach for this when you already hold an asset id; if you hold a render id instead, Shotstack: Get Assets By Render is the node you want.
Shotstack: Get Assets By Render
shotstack_get_assets_by_render
Get the CDN-hosted files a render produced. This is the honest last step of a render workflow: the url on the render status response is a temporary file, and the url here is the durable CDN copy. Returns an ARRAY, because one render can emit several files - the video plus a poster image or thumbnail if the output asked for them. Note the Serve API uses the JSON:API envelope, so paths read data.data[].attributes.url, not data.response. Only meaningful once the render status is done.
Shotstack: Get Assets By Rendition
shotstack_get_assets_by_rendition
Get the hosted asset for one rendition - a transcode produced from an ingested source, such as a 720p copy of a 1080p upload. Use it when a workflow needs the smaller version's CDN url rather than the original's.
Shotstack: Get Assets By Source
shotstack_get_assets_by_source
Get the hosted assets belonging to an ingested source file. Use it to turn a source id from the Ingest API into the CDN url a clip should point at. Returns an array in the JSON:API envelope.
Shotstack: Get Render Status
shotstack_get_render
Check where a render has got to. This is the node a workflow polls and branches on. data.response.status moves queued -> fetching -> rendering -> saving -> done, and any state can become failed instead; only done means data.response.url holds a playable file, and only failed populates data.response.error. Poll on an interval of several seconds rather than continuously: the Edit API allows 300 requests per minute in production and 150 in the sandbox, and a tight loop on one long render can spend a real share of that. The url returned here is a TEMPORARY file (Shotstack documents 24-hour storage) - take the durable CDN copy from Shotstack: Get Assets By Render.
Shotstack: Get Source
shotstack_get_source
Get one ingested source file: its Shotstack-hosted url, the original input url it came from, its width, height, duration and frame rate, and any renditions produced from it. Poll this after Shotstack: Fetch Source File until data.data.attributes.status is ready - the lifecycle is queued, importing, ready, failed, and a source that is not ready cannot be used in an edit. Renditions carry their own per-rendition status, which lags the source's.
Shotstack: Get Template
shotstack_get_template
Fetch one template in full, including the entire stored edit at data.response.template. Use this to read a template's timeline before rendering it, or to copy an existing edit into a new template.
Shotstack: Inspect Media File
shotstack_probe_asset
Read the technical metadata of a media file at a public URL, using FFprobe: duration, width and height, frame rate, codecs, bitrate and the audio and video streams it contains. Renders nothing and costs nothing. Run it before building a timeline so clip lengths can be computed from the real duration instead of guessed. The file must be reachable by Shotstack without authentication.
Shotstack: List Sources
shotstack_list_sources
List the source files ingested into this account, with each file's hosted url, dimensions, duration, frame rate and ingest status. This is the node the source pickers in other Shotstack nodes read from. Sources persist until deleted, unlike render output. Uses the JSON:API envelope, so paths read data.data[].attributes.source.
Shotstack: List Templates
shotstack_list_templates
List every saved template on the account, with its id, name and timestamps. This is the node the template pickers in other Shotstack nodes read from, and it is also the cheapest way to confirm a credential works: no parameters, no ids, and it renders nothing. Templates are per environment, so a sandbox credential lists sandbox templates only.
Action nodes 10
Shotstack: Create Direct Upload URL
shotstack_create_upload_url
Get a signed URL that a browser or script can PUT a file straight to, without ever seeing the API key. This node does NOT upload anything: it returns the signed url and its expiry at data.data.attributes, and something else does the PUT. Use it when the file lives on a user's machine rather than at a public URL; when it already has a URL, Shotstack: Fetch Source File is simpler. After the PUT completes, poll Shotstack: Get Source with the returned id until the status is ready.
Shotstack: Create Template
shotstack_create_template
Save an edit as a reusable template. Creating a template renders nothing and costs nothing; it just stores the JSON. Put handlebars placeholders such as {{ FIRST_NAME }} in the timeline and Shotstack: Render Template can then fill them in per render, which is how one design becomes many personalized videos. Returns the new template's id at data.response.id.
Shotstack: Delete Asset
shotstack_delete_asset
DESTRUCTIVE AND IRREVERSIBLE. Delete a hosted asset from Shotstack storage. The CDN url stops working immediately, which breaks every page, email or post already pointing at it, and there is no trash and no undo. The only way back is to render the video again, which costs credits again. Returns 204 with an empty body.
Shotstack: Delete Source
shotstack_delete_source
DESTRUCTIVE AND IRREVERSIBLE. Delete an ingested source file and the renditions made from it. There is no trash and no undo: the footage has to be uploaded or fetched again, and any saved template or timeline referencing its hosted url starts failing at render time rather than at delete time, which is the worst place to find out. Videos already rendered from it are unaffected. Returns 204 with an empty body.
Shotstack: Delete Template
shotstack_delete_template
DESTRUCTIVE AND IRREVERSIBLE. Delete a template and the edit stored in it. Shotstack keeps no version history and no trash, so the JSON is gone unless you saved a copy, and any workflow that renders by this template id starts failing. Videos already rendered from it are unaffected. Returns 204 with an empty body.
Shotstack: Fetch Source File
shotstack_fetch_source
Pull a video, image, audio or font file from a URL into Shotstack storage so edits can use it without refetching it every render. Shotstack downloads the URL server-side. ASYNCHRONOUS: the response carries only the new source id at data.data.id, and the file is not usable until Shotstack: Get Source reports status ready. Optionally asks for renditions (smaller transcodes) at the same time. Ingested files are stored until deleted.
Shotstack: Render Template
shotstack_render_template
Render a saved template, optionally substituting merge fields into its placeholders. ASYNCHRONOUS in exactly the same way as Shotstack: Render Video: it returns a render id at data.response.id and nothing else, and the workflow polls Shotstack: Get Render Status from there. This is the node a bulk personalization workflow loops over: one template, one merge array per recipient. SPENDS PLAN CREDITS per render, and there is no cancel.
Shotstack: Render Video
shotstack_render_video
Submit an edit to be rendered into video, audio or an image. ASYNCHRONOUS: this returns a render id immediately and the file does not exist yet. Feed data.response.id to Shotstack: Get Render Status and poll until the status is done or failed, then take the durable CDN copy with Shotstack: Get Assets By Render. SPENDS PLAN CREDITS: on a production credential this consumes render minutes and can bill the account, generative AI clip types cost extra credits even in the sandbox, and Shotstack documents no way to cancel a queued render, so a mis-triggered render is money spent rather than a mistake undone. Sandbox renders are watermarked and capped at ten minutes.
Shotstack: Transfer File To Hosting
shotstack_transfer_asset
Copy a file from a URL into Shotstack hosting or on to a configured destination, without rendering anything. Shotstack fetches the URL server-side, so the file never passes through this automation. ASYNCHRONOUS: the response comes back with status queued, and Shotstack: Get Asset reports when it is ready. Useful for putting a finished third-party file behind the same CDN as your renders.
Shotstack: Update Template
shotstack_update_template
Replace a template's name and stored edit. This is a PUT, so it OVERWRITES: send the whole edit, not a fragment, because whatever is omitted is gone. Shotstack keeps no version history, so fetch the current template first if you need to be able to put it back. Renders already submitted from the old version are unaffected.
Using the integration
On the automation canvas
Shotstack nodes chain with every other node. A new database row can supply the merge fields for Shotstack: Render Template, a schedule can drive the polling branch on Shotstack: Get Render Status, and the CDN URL from Shotstack: Get Assets By Render can be written back onto the record that started it or posted into a channel. Two values do most of the wiring: the render id, which exists only in the submit node's response and is not listed anywhere, and the template id, which most fields offer as a picker sourced from Shotstack: List Templates and labelled with each template's name and the time it was last updated.
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 ten read nodes are the comfortable surface to hand an agent: list and read templates, inspect a media file before committing to it, check a render's status, and collect hosted assets. Keep the three destructive nodes behind conditions or approval steps, and treat the two render nodes with the same care even though they destroy nothing, because each submission spends credits and cannot be cancelled. Shotstack publishes an MCP server of its own, documented in its guide with a tools reference, and it is worth knowing about: for an assistant that helps you write Shotstack edits inside your editor or client config, the vendor's server is the closer fit. This integration is the production side of the same platform, where a render is submitted off a trigger, polled by the workflow, and its durable link filed automatically.
The asynchronous render, start to finish
A render is three steps, and skipping the middle one is the most common mistake here. First, Shotstack: Render Video or Shotstack: Render Template submits and returns a render id with a queued status. A render id is not a video: a workflow that pipes it into an email is emailing an identifier. Second, Shotstack: Get Render Status is polled, and the workflow branches on the STATUS rather than on the URL, because the output URL is populated only when the status reads done and the error only when it reads failed. Shotstack documents render time at roughly twenty seconds per minute of video, more with effects, filters or transitions, so give the loop room and give it a ceiling that opens a task instead of running forever. Third, Shotstack: Get Assets By Render collects the durable file. That third step is not optional if the link is going anywhere permanent, which the next section explains.
Temporary output and the durable CDN copy
The URL on the render status response is a temporary file, and Shotstack documents temporary storage measured in a day. A workflow that writes it into a CRM record, an email or a web page has published a link that breaks tomorrow, and it will look correct in every test you run today. The durable copy is the hosted CDN asset, which is what Shotstack: Get Assets By Render returns. Three sibling nodes reach the same hosting by other routes: Shotstack: Get Asset when you hold an asset id, Shotstack: Get Assets By Source to turn an ingested source into the CDN URL a clip should point at, and Shotstack: Get Assets By Rendition for a transcode such as a 720p copy of a 1080p upload. Shotstack: Transfer File To Hosting copies a file from a URL into hosting or on to a configured destination without rendering anything.
Getting footage in: fetch, upload, and the ready state
Shotstack: Fetch Source File pulls a video, image, audio or font file from a URL into Shotstack storage so edits can use it without refetching it every render, and Shotstack downloads it server-side so no bytes pass through the automation. It is asynchronous: poll Shotstack: Get Source until the ingest status reads ready, because a source that is still importing cannot be used in an edit and renditions carry their own status which lags the source's, so a source can be ready while its smaller transcode is not. Shotstack: Create Direct Upload URL is the other route: it returns a signed URL that a browser or a script can PUT a file to without ever seeing the API key, plus its expiry. That node uploads NOTHING itself, which is the point. One documented detail belongs with it: text formats such as subtitle and caption files need either a filename on the request or a content type set on the PUT, or the type cannot be detected. Shotstack documents its file size caps as 5GB per individual source file and 10GB for combined source footage plus output, and stores ingested files in its Sydney region, which is worth knowing if you have a data-residency requirement.
Templates, merge fields and the PUT that overwrites
Shotstack: Create Template saves an edit as reusable JSON, which renders nothing and costs nothing. Put handlebars placeholders in the timeline and Shotstack: Render Template substitutes merge fields into them at submission, which is how one saved edit becomes a per-customer video. Shotstack: Get Template fetches a template in full, including the entire stored edit, which is the node to run before changing anything, because Shotstack: Update Template is a PUT and OVERWRITES: send the whole edit, since whatever is omitted is gone and Shotstack keeps no version history. The safe pattern for an automated edit is get, modify, then update, in the same run.
Callbacks, and what Mattering does and does not receive
The render submissions and the ingest fetch all accept a callback URL. It is a real Shotstack feature and it is worth using, but it points at an endpoint YOU control: nothing in this integration listens for it. The supported way to make a finished render start another workflow is to point the callback at an inbound webhook trigger in Mattering, whose URL you copy from that trigger. Otherwise, poll Shotstack: Get Render Status on a schedule, which is what most workflows here do. If you do use a callback, Shotstack's documented retry behaviour matters to whatever receives it: any response outside the success range, or slower than ten seconds, counts as a failure, and it retries up to ten times with backoff over roughly the following hour.
The three destructive nodes, gated
Shotstack: Delete Template removes the stored edit, and because Shotstack keeps no version history and no trash, the JSON is gone unless you saved a copy, while any workflow rendering by that template id starts failing. Videos already rendered from it are unaffected. Shotstack: Delete Asset stops the CDN URL working immediately, which breaks every page, email or post already pointing at it, and the only way back is to render again, which costs credits again. Shotstack: Delete Source removes ingested footage and its renditions, and it is the worst of the three in practice because the failure surfaces LATER, at render time, in a saved template still referencing the hosted URL: deleting at nine in the morning and discovering it during an afternoon batch is the realistic version. The pattern for all three is the same: gate them behind a condition or an approval task rather than a bare trigger, run Shotstack: Get Template or the relevant read first if anything downstream depends on what is there, and keep them out of any path an agent can reach unattended.
Troubleshooting
Test Connection fails with a 401
Edit nodes work but a Serve or Ingest node fails
The render finished but the output URL is empty
A render URL that worked yesterday is broken today
HTTP 429 from a workflow that polls a render
A render fails on a source file that opens fine in a browser
A source is ready but the render still cannot use it
Updating a template lost most of the edit
A workflow expecting Mattering to receive Shotstack's callback never continues
Related
The Shotstack MCP
What connecting Shotstack 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.
Shotstack 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.