FAQ: Deprecation of Bookmarks and Collections in Prismic API

Prismic Administrative Support FAQs
,
1

What are Bookmarks and how were they used?

Bookmarks were an older feature in the Prismic API, acting as a precursor to the UID field. They allowed users to query documents based on a URL slug. Since the introduction of the UID field, bookmarks have become redundant.

How can users transition from Bookmarks to UID?

  1. Add a UID Field: Add the UID field to the custom types previously using bookmarks.
  2. Migrate Bookmarks: Use the current bookmark values as the UID values.
  3. Update Queries: Adjust queries to retrieve documents via UID instead of bookmarks.
  4. Use the Migration API: To simplify the process, consider using Prismic's Migration API.

Other Considerations:

  • Tagging Specific Pages: Bookmarks were often used to tag specific pages, like a homepage.
    • For example, you might have a bookmark pointing to a homepage document.
    • To replace this, you could rely on custom tags or a custom type to uniquely identify the document.
  • Singleton Custom Types: Another approach is to use a singleton custom type (a custom type intended to hold only one document).
    • This method removes the need for a UID and provides a reliable way to target a specific page (e.g., a homepage).
    • Queries can directly reference the singleton custom type without requiring additional identifiers like UIDs.

By combining these approaches, users can flexibly transition away from bookmarks while maintaining their ability to target specific documents or pages.

What are Collections, and how were they used?

Collections were used primarily for organizational purposes in the Prismic editor. They could also be used to query documents, but this was uncommon.

How do Collections work with API v1 and v2?

  • Collections were tied to specific custom types and tags.

  • In API v1, they appeared in the "forms" object in the response. For example:

    "forms": {
    "config-nav-footer": {
        "name": "Config/Nav/Footer",
        "method": "GET",
        "rel": "collection",
        "action": "https://example.cdn.prismic.io/api/v1/documents/search",
        "fields": { ... }
    }
}

  • These persisted filters can be replicated using custom queries on custom types and tags.

What will change in the API response with this deprecation?

  1. Forms like "config-nav-footer", "landing-pages", and similar custom forms will no longer appear in the response.
  2. Tags will remain unchanged.
  3. The "everything" form will still be available and can be used for broader queries.

Updated API response example:

Before:

"forms": {
    "config-nav-footer": { ... },
    "everything": { ... },
    "tags": { ... }
}

After:

"forms": {
    "everything": { ... },
    "tags": { ... }
}

Does this impact all repositories?

No, this change primarily affects very old repositories that still rely on bookmarks or collections. Most users with modern repositories or using UIDs and tags will not be affected.

What about SDKs like Java that use API v1?

For users of the Java SDK or similar SDKs:

  1. The removal of collections will not break the default “everything” form.
  2. Users can continue querying documents using filters based on custom types and tags.

When will this change take effect?

  • The change will occur at publication time after the deprecation is deployed on 12/02/2025.
  • Custom forms tied to collections will disappear once any document is republished.

Recommendations for Users

  1. Review Existing Queries: Check if your project queries collections or bookmarks.
  2. Update Queries: Transition to UIDs and tag-based filters.
  3. Test Changes: Use a test repository to validate the impact of these changes.

For further assistance, please reach out to the Prismic support team.