Fragments API

The Fragments API provides endpoints for working with shared content fragments. Fragments are reusable content components (MDX or Puck) that can be referenced across multiple pages. Unlike pages, fragments are not site-scoped by default — they exist globally, though site-specific fragments can shadow global ones.

All endpoints are relative to the API base URL (default: /__cms/api).

List Fragments

GET /fragments

List all fragments with optional filters. When the site parameter is provided, returns a merged list of global and site-specific fragments with scope annotation (site fragments shadow global fragments with the same name).

Parameters:

Name	In	Type	Required	Description
collection	query	string	no	Filter by collection (default: all)
locale	query	string	no	Filter by locale
site	query	string	no	If provided, return merged global + site-specific fragments (Dev Branch Preview)

Response: 200 OK

{
  items: ContentManifest[]
  total: number
}

Example:

# List all global fragments
curl http://localhost:4321/__cms/api/fragments

# List fragments for a specific collection
curl "http://localhost:4321/__cms/api/fragments?collection=components"

# List merged fragments for a site (site-specific + global)
curl "http://localhost:4321/__cms/api/fragments?site=default"

Check Fragment Name Availability

GET /fragments/name-available

Check whether a fragment name is available within a collection. Useful for validating names before creating or renaming fragments.

Parameters:

Name	In	Type	Required	Description
name	query	string	yes	Fragment name to check
collection	query	string	no	Collection to check in (default: `components`)
locale	query	string	no	Locale to check in (default: `en`)
excludeId	query	string	no	Exclude this content ID from the check (for rename operations)
site	query	string	no	Check availability in site-specific scope (Dev Branch Preview)

Response: 200 OK

// Available
{
  available: true;
}

// Taken
{
  available: false;
  existingId: string; // ID of the fragment using this name
}

Errors:

Status	Code	Description
400	MISSING_REQUIRED_FIELD	`name` query parameter not provided

Example:

curl "http://localhost:4321/__cms/api/fragments/name-available?name=hero-banner&collection=components"

Get Fragment by Name

GET /fragments/:name

Get a fragment by its name. When the site parameter is provided, looks up the site-specific fragment first, falling back to the global fragment.

Parameters:

Name	In	Type	Required	Description
name	path	string	yes	Fragment name
collection	query	string	no	Collection to look in (default: `components`)
locale	query	string	no	If provided, return only this locale’s data
site	query	string	no	Site-first lookup: check site fragments, then global (Dev Branch Preview)

Response: 200 OK

// ContentManifest (or filtered to single locale)
{
  id: string
  type: 'puck' | 'mdx'
  kind: 'fragment'
  collection: string
  locales: {
    [locale: string]: {
      locale: string
      etag: string
      created: string
      modified: string
      name: string
      meta: ContentMeta
    }
  }
}

Errors:

Status	Code	Description
404	CONTENT_NOT_FOUND	No fragment with this name in the specified collection

Example:

# Get a fragment by name
curl "http://localhost:4321/__cms/api/fragments/hero-banner?collection=components"

# Get a fragment with site-first lookup
curl "http://localhost:4321/__cms/api/fragments/hero-banner?site=default"

# Get only the English locale
curl "http://localhost:4321/__cms/api/fragments/hero-banner?locale=en"