Migration API PUT /documents/:id accepts request (updates title) but ignores tags (tags never change / not reflected)

Developing with Prismic
,
1

Impacted feature

  • Prismic Migration API document update endpoint: PUT /documents/:id

  • Specifically: updating document tags on existing documents

What steps have you taken to resolve this issue already?

  • Confirmed the request is being applied by updating title successfully (response reflects the new title).

  • Ensured the update payload includes full data (not a partial patch).

Errors

  • No error returned for the tags issue.

  • The API returns a success response, e.g.:

    {
  "id": "aUwdNRQAACUAWnxs",
  "type": "article",
  "lang": "en-us",
  "title": "test title",
  "uid": "test-uid"
}

  • Despite sending tags, tags do not change and are not present in the success response.

    Your Role

    • Developer / Engineer (implementing automated content maintenance via Prismic APIs)

    Hosting provider

    • Node server

      ok - this one is llm generated, now a bit from myself : tags are not being updated via migration api, as I use it with simple fetch call. I tried to modify other things - and that works, with the title for example. But the tags - it seems that they are just being ignored.

2

Hey @dev40 !

I don’t see anything wrong with the request itself. The fact that other fields are updating suggests the call is going through, which makes this more about how tags are handled than the payload failing outright.

One thing worth double-checking is that tags is nested under data, for example:

{
  "uid": "test-uid",
  "data": {
    "tags": ["Tag1", "Tag2"]
  }
}

If that already matches what you’re sending, try stripping the payload down to just uid + tags and see if it behaves any differently.

Also worth keeping in mind that writes via the Migration API land as drafts, so it’s worth checking the draft version in the UI rather than the published one.

If none of that changes anything, this might just be a Migration API limitation or bug. Tags aren’t called out explicitly in the docs, and this kind of silent “accepted but ignored” behavior wouldn’t be the first time.

Try the minimal payload + draft check first and see if anything changes.

3

Hey Pau, thanks for your reply!

tags object does not belong to “data“, at least in my case :

image
image797×510 31 KB

So - adding tags to the data object gives me the following :

response : {
message: 'Validation failed',
details: [
{
property: 'data.tags',
value: [Array],
error: 'The field tags is not part of the Custom type'
}
]
}

I come to the conclusion, that it is a bug… and very unfortunate one, since I have a need to update tags on > 1000 documents here.
Not sure how to raise a bug concern here - and if that makes any effect at all?)

4

Hey,

Thanks for following up on this. After double checking, you are right and I want to clarify and correct an earlier assumption.

Tags are not part of the data payload.

As documented here Fetch Content — Prismic Docs , tags live at the document root level, alongside fields like id, uid, type, etc. They are not stored or updated under data.

Because of that, updating data via the Migration API will correctly update structured fields (like the title), but will not affect tags. This explains why your PUT /documents/:id requests successfully update the title while tags remain unchanged.

So to be explicit:

  • This is expected behavior based on the current API contract.

  • Tags cannot be updated via the data object.

  • The Migration API currently does not support updating document tags.

Given the use case described here, we have created a feature request internally to support updating tags via the Migration API. We cannot guarantee timelines, but this will be reviewed by the product team and considered alongside other roadmap items.

Sorry again for the earlier confusion, and thanks for flagging this and pushing on it.