Cannot Fetch Documents from a Migration Release — Always Falls Back to Master

Developing with Prismic
1

Describe your question/issue in detail

Hi,

I'm working on a tool to automate migrations in Prismic. Everything is working about 95%, but I'm running into one issue regarding fetching content that lives inside a migration release (not master).

Here’s the step-by-step breakdown of what works so far:

What works:

  1. Creating first-level pages (custom page type) → Works perfectly
  2. Creating second-level pages (linked to the first-level ones) → Also works fine

So at this point, I've created:

  • A document of type Sector
  • A document of type Article

These are now sitting in the Migration release (not published yet).

The problem:

When the migration script continues and detects that the Sector already exists (great!), it should then:

  1. Pull that document from the migration release (not from master)
  2. Extract the id and data
  3. Proceed to link or extend from that content

But I can't seem to fetch content from the Migration release — it always returns content from the published documents (master), even though I'm passing the correct ref.

What I’ve tried:

  1. I get the release ref:

const allReleases = await client.getReleases(); // Gets correct migration release ref
const masterRef = await client.getMasterRef(); // Confirmed not using this

  1. I try to tell the client to use the release ref:

client.queryContentFromRef("the-migration-ref");
// No effect

  1. I try to force the ref when creating the client:

const client = prismic.createClient("https://my-repo.cdn.prismic.io/api/v2", {
accessToken: "my-access-token-with-permissions",
ref: "the-migration-ref",
});

// Still, it only fetches published documents.

  1. I try using writeClient with the write API token:

const writeClient = createWriteClient(“my-repo", {
writeToken: "my-write-token",
accessToken: "my-access-token",
});

// Same issue — I can create just fine, but when trying to getByUID() or getAllByType(...), I still get only master documents.

The question:

How can I force my client (or any method) to fetch from a specific release ref (i.e., the Migration release), so that I can access documents that exist only there?

I’m explicitly passing the ref in the query but getting back content only from the master. Is there something special about querying unpublished content in a release that I’m missing?

Thanks in advance!

2

It should be possible to query documents from a migration release by using its specfic ref, but that ref won’t show up in the API until the migration release is made available as a “regular release”. Like one ones you create in the UI of the page builder.

Once that’s done, I think then you can use the release’s ref in your queries

Migration API Feedback
3

Yes, it’s not possible until it’s made a regular release. It’s like they’re completely separate. The idea was to make the tool automatically publish documents generated by AI. Now it’s kind of working 90% of the process is automatic which is pretty good, but it’s limited to the migration release only, which is okay. It’s a shame that the master and migration are two different APIs, and that the migration can’t be fetched like a normal release — because if that were the case, I could automate the whole process.