Menu

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.

Sign in to the Shotstack dashboard and open the API Keys page.
Copy the key for the environment you want to connect. Start with the sandbox key unless you have a reason not to.
A production key spends real plan credits on every render it submits, and Shotstack documents no cancel endpoint for a queued render. Connect the sandbox first, build the workflow there, and switch the environment only when the edit is right.
You do not need a base URL, a region or a project id. The key selects the account, the environment on the credential selects the environment, and each node already knows which of the three APIs it belongs to.

Connect Shotstack to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Shotstack from the list.
Click Create new credential, paste the API key, and set Environment to match the key you pasted.
This is the field most worth getting right first time. A Shotstack key issued for one environment does not authenticate against the other, and a mismatch does not produce a helpful message: it produces a 401 that reads like a broken integration.
The credential is stored encrypted in Google Secret Manager and never appears in workflow logs.
Click Test Connection. Mattering lists templates on the Edit API for this credential's own environment. It is the only parameterless read on the surface, it renders nothing and costs no credits, and a pass proves the host, the API prefix, the environment segment and the header name together.
Click Connect. All 20 Shotstack nodes appear in your canvas palette.

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
The overwhelmingly likely cause is a key and environment mismatch rather than a bad key. Shotstack issues a separate key for its sandbox and production environments, so a sandbox key on a credential set to production does not authenticate. Open the credential, check the Environment field against where you copied the key from in the dashboard, and try the other value before assuming the key is wrong. After that, check for leading or trailing whitespace from the copy and confirm the key still exists on the dashboard's API keys page.
Edit nodes work but a Serve or Ingest node fails
That split is the three-API design showing itself, and it is why the verify section asks for a read from each. Shotstack is three path prefixes on one host, each with its own routing and its own rate-limit bucket, and the connection test only exercises Edit. A failure isolated to one prefix is usually about the id being passed rather than the credential: Serve nodes want an asset, render, source or rendition id, and Ingest nodes want a source id, and those come from different places. Run Shotstack: List Sources on its own to confirm Ingest answers for this credential, then work back to the failing node's id.
The render finished but the output URL is empty
Read the status before the URL. Shotstack populates the output URL only when the status reads done, and the error only when it reads failed, so a poll that reads the URL unconditionally gets nothing on every pass until the last one, and gets nothing forever if the render failed. Branch on data from Shotstack: Get Render Status first: continue on done, route to a task on failed, and keep waiting on queued, fetching, rendering or saving. Give the loop an overall ceiling too, since Shotstack documents render time at roughly twenty seconds per minute of video and more with effects, so a short timeout can give up on a render that was going to succeed.
A render URL that worked yesterday is broken today
The workflow stored the temporary file rather than the durable one. The URL on the render status response is temporary storage, documented in days rather than indefinitely, so it is fine to preview and wrong to publish. Add Shotstack: Get Assets By Render after the poll and store the CDN URL it returns instead. If the link has already gone out, the asset is usually still retrievable through that node using the same render id, so you may not have to re-render; if the asset itself was deleted, re-rendering is the only route back and it costs credits again.
HTTP 429 from a workflow that polls a render
That is the rate limit, and a tight poll loop is the realistic way to reach it from an automation. Shotstack documents its limits per API key, per sixty-second window, per API, with different figures for production and sandbox: 300 and 150 on Edit, 600 and 300 on Serve, 300 and 120 on Ingest. Space the polls several seconds apart, which is well within what a render needs anyway, and remember the buckets are separate, so moving the asset collection to Serve does not consume the Edit budget the poll needs.
A render fails on a source file that opens fine in a browser
Every URL Shotstack fetches must be publicly reachable WITHOUT authentication, and that applies to media inspection, source fetches, transfers and every clip source inside a timeline. A signed URL, an expiring share link or anything behind a session cookie can work perfectly in your browser and fail server-side. Test the address with Shotstack: Inspect Media File before spending a render on it: it reads duration, dimensions, frame rate, codecs and bitrate, renders nothing, and tells you immediately whether Shotstack can reach the file at all.
A source is ready but the render still cannot use it
Check the renditions rather than the source. The ingest lifecycle moves from queued through importing to ready, and renditions produced from a source carry their OWN status which lags the source's, so a source can read ready while its 720p copy is not. Read Shotstack: Get Source in full and look at the renditions rather than only the top-level status, and where the edit points at a smaller version, poll until that rendition is ready too. Shotstack: Get Assets By Rendition is what turns a rendition into the CDN URL a clip should point at.
Updating a template lost most of the edit
That is the documented behaviour rather than a fault: Shotstack: Update Template is a PUT, so it replaces the stored edit wholesale and anything omitted is gone. Shotstack keeps no version history, so there is nothing to roll back to. The safe pattern is get, modify, update in one run: fetch the current template with Shotstack: Get Template, which returns the entire stored edit, change the part you meant to change, and send the whole thing back. If the template was already overwritten, the only route back is rebuilding it, which is also the argument for keeping a copy of important edits outside Shotstack.
A workflow expecting Mattering to receive Shotstack's callback never continues
Nothing in this integration listens for Shotstack's callback, and that is the failure worth naming because it is silent: the first half of the workflow succeeds and the second half simply never starts. The callback field on the render and fetch nodes points at an endpoint you control. To make a finished render start another workflow, create an inbound webhook trigger in Mattering, copy its URL into the callback field, and build the follow-on workflow from that trigger. The alternative, and the simpler one for most cases, is to poll Shotstack: Get Render Status on a schedule in the same workflow that submitted the render.

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.

Start Free Explore our Products