Menu

Mattering Automations Prismic integration

Connect Prismic to Mattering Automations: content queries with the full filter grammar, page types and shared slices, the media library, and Migration API document writes as workflow steps, built around one repository and up to two optional tokens.

The Mattering Automations Prismic integration puts four separate Prismic APIs on your automation canvas: query published content with Prismic's full filter grammar, read and change page types and shared slices, list and upload and manage media, and write documents through the Migration API. That is 23 nodes over 18 documented endpoints, 12 of them reads and 11 of them actions, with 3 flagged destructive.

The credential is unusual for an integration and easier to understand up front than to discover later. The only required field is the repository NAME, because that is what builds the content host and what identifies the repository on the other three. Both tokens are optional. Reading a PUBLIC repository needs no token at all, which was verified live during the build rather than assumed. A private repository needs a Content API access token. The Custom Types, Asset and Migration nodes need a write token, which is minted inside that one repository and works nowhere else. A connection with no write token is a valid setup: it connects, it reads content, and Test Connection tells you that ten of the twenty-three nodes will not run.

One more thing is worth knowing before the first query. Prismic rejects a content query that carries no ref, and a ref names a VERSION of your content rather than being a static setting, so publishing rotates it and a pasted ref goes stale. The integration fetches the master ref itself, caches it briefly per repository, and refreshes it and retries once when a content query answers 404 because a publish moved it. You never paste one. Every content node still carries an optional Ref field with a picker over your repository's refs, so a workflow can deliberately read a Release instead, and a ref you name explicitly is never silently swapped for master.

Before you start

  • A Prismic repository, and its name. The name is the subdomain in your Prismic dashboard URL, and it is the only value the connection actually requires. Paste a full host or URL and the integration trims it back to the subdomain.
  • A Content API access token, only if the repository's content is private. Public repositories are readable with no credential, so most read-only setups need nothing here.
  • A write token, only if you want the model, media or Migration nodes. It is created inside the repository under its API and Security settings, in the Write APIs section, or from the Prismic CLI. Ten of the twenty-three nodes need it, including two nodes that only READ: Prismic: List Page Types and Prismic: List Shared Slices require a write token because the Custom Types API ships no read-only credential.
  • One credential per repository. A Prismic write token belongs to a single repository and is accepted by no other, so production and staging repositories need a connection each.
  • A Mattering workspace with access to the Automations app.
  • Prismic's pricing page lists the Custom Types, Asset and Migration APIs as included on every plan, free included, so the write half of this integration is not plan-gated. What varies by plan is the monthly API call allowance, so check the allowance on your own plan rather than the feature list.

Gather your repository name and tokens

Prismic addresses one repository four different ways: as the host on the Content API, and as a repository header on the Custom Types, Asset and Migration APIs. A write token is minted inside one repository and accepted by no other, and the Content API access token is a per-repository setting too, so the whole connection is scoped to exactly one repository. That is why the repository name lives on the credential rather than as a required field on every node with only one legal value.

Open your Prismic dashboard and note the repository name. It is the subdomain of the dashboard URL.
If the repository's content is private, open its Settings and then API & Security, and create a Content API access token. Skip this step for a public repository.
For the model, media and Migration nodes, stay in API & Security, open the Write APIs section, and create a write token. The Prismic CLI creates the same thing if you prefer.
A Prismic write token has no scopes you can compose and no introspection endpoint. All three write hosts answer an unauthorized request with HTTP 403 and an EMPTY body, so a token that exists but lacks privilege looks exactly like a token that is wrong. Treat any 403 on a write node as a token question first, and keep write tokens out of connections that only need to read.
You never supply a ref, an API version or a host. The ref is fetched and refreshed for you, the API version is pinned by the integration, and the content host is built from the repository name.

Connect Prismic to Mattering

In Mattering Automations, open Connectors and click Add Connector.
Choose Prismic from the list.
Click Create new credential. Fill in Repository, then paste an Access Token or a Write Token only if your setup needs them, and save.
Credentials are stored encrypted in Google Secret Manager and never appear in workflow logs. The repository name is not a secret and is stored as an ordinary field.
Click Test Connection. Mattering reads the repository root, and it additionally reads the Custom Types list only when you supplied a write token, because the Content API never sees that token and nothing else can prove it. The success message reports how many page types the repository holds, so you can confirm at a glance that you connected the repository you meant to.
Click Connect. All 23 Prismic nodes appear in your canvas palette.

Verify it works

Open any automation canvas and check the palette for a Prismic section listing the read and action nodes. Drop Prismic: Get Repository onto the canvas and run a test step. It is the natural probe: it takes no required parameters, it is the one node that works on a public repository with no token at all, and it returns everything the other nodes' pickers read from. In the response you should see the refs, the tags, the locales, and two convenience values the integration adds beside Prismic's own fields: master_ref, lifted out of the refs list, and type_list, which is Prismic's page type MAP turned into rows so a picker can use it.

Now try a real content query. Drop Prismic: List Documents By Type onto the canvas, open the Document Type field, and confirm the picker lists your page types by their display labels rather than raw ids. Choose one and run the step. You get the standard paginated envelope with total_results_size, total_pages and a results array, each result carrying its id, uid, type, tags, publication dates, locale and a flat data object keyed by your model's own field names. Leave Ref blank: the integration supplies the master ref and refreshes it across publishes, so a blank ref is the correct setting for reading published content.

If you connected a write token, verify that half separately, because a content success proves nothing about it. Drop Prismic: List Page Types onto the canvas and run it. A bare JSON array of page types means the write token is accepted, so paths read data[].id with no wrapper key. HTTP 403 with an empty body means the write token is missing, wrong, or not privileged enough, and those three are indistinguishable from the response alone. Everything in this verify path is read-only, so it cannot reach the three destructive nodes and is safe to re-run whenever you rotate a token.

Node reference

23 nodes, generated from the connector itself so this reference always matches what ships.

Read and query nodes 12

Prismic: Get Document By ID

prismic_get_document_by_id

Fetch one document by its Prismic id. Builds the at(document.id, ...) filter for you and returns the same paginated envelope every content query returns, with the single document in data.results[0] -- Prismic has no fetch-one endpoint, so a result count of zero is how a missing or unpublished document reports itself rather than a 404. Set lang to * if the id might belong to a translation rather than the master locale, otherwise a document that exists in another locale looks missing.

Prismic: Get Document By UID

prismic_get_document_by_uid

Fetch one document by its human-readable UID, which is how a website resolves a URL slug to content. Builds the at(my.<type>.uid, ...) filter, so it needs the page type as well as the uid: a UID is unique within a page type and a locale, not across the repository. Returns the standard paginated envelope with the document in data.results[0]; zero results means no document with that uid in that type and locale. Page types with no UID field cannot be queried this way at all.

Prismic: Get Page Type

prismic_get_custom_type

Read one page type's full definition: its label, whether it is repeatable and active, and the model JSON describing every tab, field and slice zone. RUN THIS BEFORE ANY UPDATE. Prismic's update endpoint REPLACES the model rather than merging into it and exposes no way to read a previous version, so the object this node returns is the only rollback you will have.

Prismic: Get Repository

prismic_get_repository

Read the repository's metadata: every ref (the master ref for published content, plus one per Release), the page types, the tags in use, the configured locales, the bookmarks, and the query form definitions. THIS IS THE ENDPOINT THAT MAKES EVERY OTHER CONTENT QUERY POSSIBLE: a Prismic content query is rejected without a ref, and the ref lives here. The other content nodes fetch it automatically, so run this node yourself only when you want the metadata itself: to pick a Release ref, to enumerate page types or tags, or to confirm which locales exist. On a PUBLIC repository this needs no credential at all, which makes it the cheapest possible check that a repository name is right. Two convenience fields are added to Prismic's response and are not part of it: master_ref (the ref whose isMasterRef is true, lifted out so a template can reach it) and type_list (the types map turned into rows so it can populate a picker).

Prismic: Get Shared Slice

prismic_get_slice

Read one shared slice's full definition, including every variation and the fields inside each. RUN THIS BEFORE ANY UPDATE: the update endpoint replaces the slice rather than merging, and no previous version is readable afterwards.

Prismic: List Assets

prismic_list_assets

List the media library: each asset's id, delivery url, filename, extension, kind, size, dimensions, alt text, notes, credits and timestamps. Filter by keyword, which searches the title, filename, alt, notes and credits fields. PAGINATION IS CURSOR-BASED, not page-based: take data.cursor from one response and pass it as cursor on the next; an absent or empty cursor means you have reached the end. This is where an asset id comes from for the update and delete nodes, and for referencing media in a Migration API document.

Prismic: List Documents By Tag

prismic_list_documents_by_tag

List every document carrying a tag, across all page types. Tags are Prismic's repository-wide, editor-managed labels, so this is how a workflow picks up 'everything the content team marked for the newsletter' without the automation knowing anything about the content model. Give one tag, or several: match_all off returns documents with ANY of them (the any filter), match_all on returns only documents carrying ALL of them (the at filter). Tags are case-sensitive.

Prismic: List Documents By Type

prismic_list_documents_by_type

List every document of one page type, optionally narrowed to a publication-date window. This is the node a content sync is built on: point it at a type, set published_after to the last time the workflow ran, and it returns only what changed since. The window filters on last_publication_date by default (what changed) or on first_publication_date (what is new), and both bounds are EXCLUSIVE, which is what makes a rolling window safe to advance without double-counting. Note that Prismic serves content from a CDN, so a document published seconds ago may not appear in the very next query.

Prismic: List Page Types

prismic_list_custom_types

List every page type (custom type) defined in the repository, each with its id, display label, whether it is repeatable, whether it is active, and its full model JSON. This is the content model itself, not content: use it to discover what types exist before querying documents, or to snapshot the model before changing it. Requires a WRITE TOKEN even though it only reads -- the Custom Types API has no read-only credential. Returns a bare JSON array, so paths read data[].id rather than data.items[].id.

Prismic: List Shared Slices

prismic_list_slices

List every shared slice in the Slice Library, each with its id, name, description and the full definition of each variation. Shared slices are the reusable page sections that page types reference in their slice zones; slices defined inline inside one page type are part of that type's model instead and do not appear here. Returns a bare JSON array, so paths read data[].id. Requires a write token even though it only reads.

Prismic: Query Documents

prismic_query_documents

Query the repository with Prismic's full filter grammar. This is the connector's complete read surface: the Content API is ONE search endpoint plus a bracketed filter language, so any query Prismic can answer can be expressed here, including ones the typed nodes beside it do not cover. Give a structured filters array and the connector assembles the q parameter for you, or paste a complete q value from Prismic's API Browser into raw_query. With neither, this returns every document in the repository, newest page first. Results come back paginated with total_results_size and total_pages; each result carries its id, uid, type, tags, publication dates, locale and its full flat data object. Leave ref blank to read published content. Reads only: a Prismic filter cannot modify anything.

Prismic: Search Documents

prismic_search_documents

Full-text search across the repository. Builds Prismic's fulltext filter, which searches rich text, title, key text, select and UID fields -- and only those: it does NOT search numbers, dates, links, embeds or image metadata, so a term that exists only in a caption field of the wrong type returns nothing. Leave the path at 'document' to search the whole document, or narrow it to one field with my.<type>.<field>. Optionally restrict to a single page type. Matching is by word, not by substring.

Action nodes 11

Prismic: Create Document

prismic_create_document

Create a page in Prismic from structured content. THE PAGE IS CREATED AS A DRAFT in a Migration Release and is NOT LIVE: it will not appear in any content query until somebody publishes the Migration Release from the Prismic dashboard, and the Migration API has no publish endpoint. A workflow that creates a document and then reads it back will find nothing, and that is correct behaviour rather than a failure. MEDIA MUST ALREADY EXIST: upload files with Prismic: Upload Asset first and reference them by id inside data. Rate limited to ONE REQUEST PER SECOND PER REPOSITORY, one page per request, so a bulk import needs pacing. Save the id from the response: it is what Prismic: Update Document needs.

Prismic: Create Page Type

prismic_create_custom_type

Create a new page type from a model JSON definition. The id must not already exist: Prismic answers HTTP 409 if it does, which is a safe failure rather than an overwrite. Success is HTTP 201 with an EMPTY BODY, so this node returns no object -- confirm with Prismic: Get Page Type. Reversible with Prismic: Delete Page Type as long as no documents have been created against it yet.

Prismic: Create Shared Slice

prismic_create_slice

Create a shared slice in the Slice Library. A slice needs at least one variation, each describing its own primary fields and repeatable items. Prismic answers HTTP 409 if the id already exists, so this cannot silently overwrite. Success is HTTP 201 with an EMPTY BODY. A new slice is not usable until a page type's slice zone references it, so expect a follow-up Prismic: Update Page Type.

Prismic: Delete Asset

prismic_delete_asset

DESTRUCTIVE and IRREVERSIBLE: remove a file from the media library. Prismic's own reference warns that deleting an asset already used on published pages RESULTS IN BROKEN FILES -- those pages keep their reference and start serving a dead URL, with no warning at delete time and no list of what will break. There is no trash and no undelete; re-uploading the same file produces a NEW id and a new URL, so existing references stay broken. Check where the asset is used before running this.

Prismic: Delete Page Type

prismic_delete_custom_type

DESTRUCTIVE and IRREVERSIBLE: delete a page type. The model definition is gone, and the Custom Types API has no trash, no versions and no undelete -- re-creating a type with the same id gives you an empty model, not the one you deleted, unless you saved the JSON first. Any documents of this type lose the model that renders and validates them. SAVE THE MODEL WITH Prismic: Get Page Type BEFORE RUNNING THIS, and prefer setting status off with Prismic: Update Page Type, which retires a type reversibly. Success is HTTP 204 with an empty body.

Prismic: Delete Shared Slice

prismic_delete_slice

DESTRUCTIVE and IRREVERSIBLE: delete a shared slice. The definition and every variation are gone, with no trash, no versions and no undelete, and every page type whose slice zone references it loses that option immediately. Content already authored into instances of this slice loses the model that renders it. SAVE THE DEFINITION WITH Prismic: Get Shared Slice BEFORE RUNNING THIS. Success is HTTP 204 with an empty body.

Prismic: Update Asset Metadata

prismic_update_asset

Update an asset's metadata: alt text, internal notes and credits, each up to 500 characters. The FILE itself is not touched and its delivery URL does not change, so nothing already published breaks. Fields you leave blank are left alone rather than cleared. Reversible by sending the previous values back.

Prismic: Update Document

prismic_update_document

Update an existing page's content. THE UPDATE IS A DRAFT: it lands in a Migration Release and the published version is untouched until somebody publishes, so the live site does not change when this node succeeds and a content query still returns the old content. THE data OBJECT IS A FULL REPLACE, not a merge -- a field left out of it is cleared in the draft, so read the current document with Prismic: Get Document By ID and edit what it returns. Type, locale and translation link CANNOT be changed and are ignored if sent. Rate limited to one request per second per repository.

Prismic: Update Page Type

prismic_update_custom_type

Replace a page type's definition. THIS IS A FULL REPLACE, NOT A MERGE: whatever you send becomes the entire model, so a field you leave out of the JSON disappears from the editor and the content already stored in it becomes unreachable through the app. Prismic's API offers no way to read a previous model version, so ALWAYS run Prismic: Get Page Type first and edit what it returns -- that response is your only rollback. Existing documents are not deleted and their stored values survive; re-adding the field with the same API id brings the content back. Prismic answers HTTP 422 if the id does not exist, and HTTP 204 with an EMPTY BODY on success, so this node returns no object.

Prismic: Update Shared Slice

prismic_update_slice

Replace a shared slice's definition. THIS IS A FULL REPLACE, NOT A MERGE: the variations you send become the entire set, so a variation or field left out disappears and the content stored in it becomes unreachable in the editor. The API exposes no previous version, so run Prismic: Get Shared Slice first and edit what it returns -- that is your only rollback. Every page type whose slice zone references this slice is affected at once. Prismic answers HTTP 422 if the id does not exist and HTTP 204 with an empty body on success.

Prismic: Upload Asset

prismic_upload_asset

Add a file to the Prismic media library by URL. THE CONNECTOR FETCHES THE URL ITSELF and forwards the bytes as the multipart upload Prismic's Asset API expects, because raw file bytes cannot travel through a canvas field. The source must be publicly reachable without authentication, and the download is capped at 20 MB. Returns the created asset, whose id is what a Migration API document must reference to use the file -- the Migration API cannot upload media itself, so this node runs first in any content-with-images workflow. One asset per request and at most one request per second. Reversible with Prismic: Delete Asset.

Using the integration

On the automation canvas

Prismic nodes chain with every other node. A schedule can run Prismic: List Documents By Type with a publication date window and push what changed into a Mattering database, a Slack message or a search index. A form submission can trigger Prismic: Upload Asset followed by Prismic: Create Document to stage a page for review. Prismic: Query Documents answers anything the typed nodes do not, because it speaks the whole filter grammar. Most of the wiring is done by pickers rather than by typing: the ref, locale, page type and tag fields are all sourced from Prismic: Get Repository, the uid picker is gated on the page type you chose, and the asset and model pickers read from their own listers.

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. An agent can search with Prismic: Search Documents, resolve a URL slug with Prismic: Get Document By UID, read the content model with Prismic: Get Page Type, and draft a page with Prismic: Create Document knowing it lands as a draft rather than going live. The read nodes plus the draft-writing Migration nodes are the comfortable surface to hand an agent; keep the three destructive nodes behind conditions or approval steps. Prismic's published documentation does not list an official MCP server of its own, so there is no vendor server to weigh this against today; its AI documentation covers using coding assistants through an installable skill instead.

The read API is a grammar, and the palette reflects that

Prismic's Content API is two endpoints, a repository root and a document search, plus a bracketed filter language of roughly thirty functions that combine with AND when several appear together. There is no wide REST surface to cut into nodes, so the integration ships the grammar as one node and the common cases as five. Prismic: Query Documents takes a structured filters array the canvas can build, template into and read back, or a complete query pasted from Prismic's own API Browser into its raw query field. Beside it, Prismic: Get Document By ID, Prismic: Get Document By UID, Prismic: List Documents By Type, Prismic: List Documents By Tag and Prismic: Search Documents build their filters internally so nothing has to be learned to do the obvious thing. Two behaviours are worth carrying into your design. There is no fetch-one endpoint in Prismic, so a missing document reports itself as a result count of zero rather than a 404. And a UID is unique within one page type and locale rather than across the repository, which is why the by-UID node needs the page type as well.

Refs, publishes and the CDN

The ref is handled for you: fetched from the repository root, cached briefly per repository, and refreshed with one retry when a content query answers 404 because a publish rotated it. Leave Ref blank on every node that reads published content. Fill it only when you want a specific Release, and pick from the list rather than pasting, because a hard-coded ref breaks at the next publish and a ref you named is deliberately never swapped for master. Separately, Prismic serves content from a CDN, so a document published seconds ago may not appear in the very next query and Prismic documents no invalidation window. Build the delay into workflows that publish and then immediately read back, rather than treating an empty result as a failure.

Changing the content model safely

Prismic: Update Page Type and Prismic: Update Shared Slice are FULL REPLACEMENTS, not merges: whatever you send becomes the entire model, so a field left out of the JSON disappears from the editor. Prismic exposes no way to read a previous model version, which makes the pattern non-negotiable rather than a style preference. Run Prismic: Get Page Type or Prismic: Get Shared Slice first, edit exactly what came back, and send the whole thing. That Get response is your only rollback. The damage is less permanent than it sounds in one respect worth knowing: existing documents are not deleted and their stored values survive a removed field, reappearing if the field is re-added with the same API id. Two response shapes will surprise a workflow otherwise: the write endpoints answer with an EMPTY body, HTTP 201 on create and 204 on update, so these nodes return no object and success is the status code alone, and creating a page type whose id already exists answers 409 rather than overwriting.

Media, and why it goes first

Prismic: Upload Asset adds a file to the media library from a public URL: the integration fetches the URL itself and forwards the bytes as the multipart upload the Asset API expects, because raw file bytes cannot travel through a canvas field. The source must be reachable without authentication and the download is capped at 20 MB. It runs BEFORE any content write that references media, because the Migration API cannot upload files and can only point at an asset that already exists. Prismic: List Assets pages by CURSOR rather than by page number: take data.cursor from one response and pass it as the cursor on the next, and an absent or empty cursor means the end. Prismic: Update Asset Metadata changes alt text, notes and credits only; the file and its delivery URL are untouched, so nothing published breaks and blank fields are left alone rather than cleared.

Migration writes land as drafts

This is the single most likely support question, so it is worth reading twice. Prismic: Create Document and Prismic: Update Document write into a Migration Release as DRAFTS. The live site does not change, the published version is untouched, and a content query still returns the old content. The Migration API has no publish endpoint, so publishing the Release is done by a person in the Prismic dashboard. A workflow that creates a document and then reads it back will find nothing, and that is correct behaviour rather than a fault. Three more constraints belong in the design: the data object on an update is a full replace, so read the current document first and edit what it returns; type, locale and translation links cannot be changed and are ignored if sent; and Prismic rate limits this API to one request per second per repository with one page per request, so a bulk import needs pacing rather than a fan-out.

The three destructive nodes, gated

Prismic: Delete Page Type and Prismic: Delete Shared Slice remove a model definition with no trash, no versions and no undelete. Re-creating a type with the same id gives you an empty model, not the one you deleted, unless you saved the JSON first, and any documents of that type lose the model that renders and validates them. Save it with the matching Get node first, and prefer retiring a type reversibly by setting its status off through Prismic: Update Page Type. Prismic: Delete Asset is the one with the widest blast radius: Prismic's own reference warns that deleting an asset already used on published pages results in broken files, those pages keep their reference and start serving a dead URL, there is no warning at delete time and no list of what will break, and re-uploading the same file produces a NEW id and URL so existing references stay broken. Put all three behind a condition or an approval task rather than a bare trigger, and keep agents on the read nodes.

Rate limits and pagination differ per API

This integration spans four APIs and they do not behave alike, which matters as soon as a workflow loops. Prismic documents the Content API at 200 requests per second and states that CDN-cached queries are not counted, and every content node here targets the CDN host specifically so it sits inside that exemption. The Migration API is one request per second per repository, one page per request. The Asset API is one asset per request and at most one request per second. Prismic does not document a limit for the Custom Types API. Pagination differs too: content takes a page number with a maximum page size of 100, plus an after cursor that is the stable way to walk a long list because page numbers re-slice if content changes mid-walk; assets page by cursor and limit; and the Custom Types and Migration APIs are not paginated at all.

Troubleshooting

Test Connection fails and the repository is spelled correctly
Check the repository name for a pasted host or path first: the field wants the subdomain, and although the integration trims a full URL back to the subdomain, a typo in the subdomain resolves to nothing. A repository name that does not exist answers HTTP 404 on the repository root rather than an auth error, so a 404 here is almost always a name problem. If the repository is private, the missing piece is a Content API access token created in that repository under Settings and then API & Security. If the test passes but reports that ten nodes will not run, that is not a failure: it is the message you get with no write token, and it is correct for a read-only setup.
A write node returns 403 with an empty response body
That is the documented shape rather than a broken response: all three write hosts answer an unauthorized request with HTTP 403 and no body at all, and the response is identical with a bad token, an under-privileged token and no token. So the failure cannot be diagnosed from the response, only by elimination. Confirm the write token was created inside THIS repository, since a token from another repository is valid and simply does not apply here. Re-run Test Connection, which probes the Custom Types list specifically to prove the write token. If the 403 is only on the Asset API while other write nodes work, the origin header the Asset API documents as required is the next thing to vary.
A read node fails while other read nodes work fine
Check which API the failing node belongs to. Prismic: List Page Types and Prismic: List Shared Slices only read, but they live on the Custom Types API and it ships no read-only credential, so they need the WRITE token like every other node on that host. This is the surprise that makes a safe read fail on a connection that reads content perfectly. The content read nodes are the other half and need no write token at all.
A query that worked last week now returns HTTP 400
Somebody probably edited a page type. Prismic rejects a typed filter aimed at a field that is missing or wrongly typed with a 400 rather than returning zero results, and nothing in the error names the filter responsible, so a number or date filter starts failing the moment its field is renamed or retyped. Untyped filters behave differently against an absent path and simply return an empty set, which is why one query can break while another survives the same model change. Two other causes of a bare 400 are worth ruling out: a content query URL longer than the 2048-character cap Prismic enforces, which the integration checks locally and names rather than letting Prismic answer with an unexplained error, and a page size above the documented maximum of 100.
A content query returns 404
A 404 on a content query is a ref problem rather than a missing document, because a missing document reports itself as zero results. If the Ref field is blank the integration handles this for you: it refreshes the cached master ref and retries once, so a publish that rotated the ref mid-run self-corrects. A persistent 404 therefore points at a ref you supplied yourself. A hard-coded ref string breaks at the next publish, and a Release ref stops resolving when the Release is published or deleted. Pick from the ref list rather than pasting, or clear the field to read published content. A ref you name explicitly is deliberately never replaced with master, because substituting it would answer a different question than the one you asked.
A document was created but no content query can find it
This is expected behaviour, not a failure. Prismic: Create Document and Prismic: Update Document write through the Migration API, and what they write is a DRAFT inside a Migration Release. Nothing is live until somebody publishes that Release from the Prismic dashboard, and the Migration API has no publish endpoint, so no node in this integration can complete the publish. Check the Migration Release in Prismic and you will find the document there. Separately, a document that IS published may still lag one query behind, because Prismic serves content from a CDN with no documented invalidation window.
A write node returned success but the response object is empty
Several Prismic write endpoints answer with an empty body by design, so this is the documented shape rather than a dropped response. Creating a page type or a shared slice answers HTTP 201 with no body, and updating or deleting either one answers HTTP 204 with no body, which means the connector envelope's data is an empty object and success is the status code alone. A workflow that needs the resulting object must re-read it with Prismic: Get Page Type or Prismic: Get Shared Slice rather than templating off the write node's output.
A field that used to hold content is empty after a model update
Prismic: Update Page Type and Prismic: Update Shared Slice are full replacements rather than merges, so a field left out of the JSON you sent is removed from the model. The stored content is better off than it looks: existing documents are not deleted and their values survive, and re-adding the field with the SAME API id brings the content back into the editor. Recover by taking the model JSON you saved with the matching Get node, restoring the missing field definition, and sending the whole model again. If no copy was saved, Prismic exposes no previous model version to read, which is why both update descriptions open by telling you to fetch first.
A template reading the page type list resolves to nothing
Two shapes catch this out. The repository root returns page types as a MAP keyed by id rather than as a list, so a path with [] in it will never resolve against it; the integration adds a type_list array beside the untouched types map for exactly this reason, and the pickers read from that. The Custom Types listers are the opposite case: they return a BARE JSON array, so paths read data[].id with no wrapper key rather than data.items[].id. Assets are a third shape again, wrapped as data.items[] with a cursor beside them.
A bulk import through the Migration API keeps failing partway
Pacing is the usual cause. Prismic rate limits the Migration API to one request per second per repository and accepts one page per request, so a fan-out over many documents will trip it. Sequence the writes and put a delay between them rather than running them in parallel. Two other constraints bite in bulk: media must already exist, because the Migration API cannot upload files, so run Prismic: Upload Asset first and reference the returned id, and the Asset API is itself limited to one asset per request at up to one request per second.

Prismic 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