GraphQL Shared Elements

Shared elements are reusable content records that can appear on several pages and across page versions. Use GraphQL to query them, create drafts, update their structured data and control their publication lifecycle.

See GraphQL Pages for page versioning and PagibleAI GraphQL API for the JSON scalar rule, authentication and request troubleshooting.

Element fields

Element

Field
Type
Meaning
id
ID!
Element UUID
type
String!
Content element type
lang
String
ISO language code
name
String
Editor-facing name
data
JSON!
JSON-encoded element data
editor
String!
Last editor
created_at / updated_at
String!
Creation and update times
deleted_at
String
Soft-deletion time
bypages
[Page!]!
Pages using the element
byversions
[Version!]!
Versions using the element
files
[File!]!
Files referenced by the element
latest
Version
Latest version
versions
[Version!]!
Version history
changed
JSON
Conflict details after an overlapping save

Query one element

query ElementDetail($id: ID!) {
  element(id: $id) {
    id
    type
    lang
    name
    data
    editor
    changed
    latest { id published publish_at }
    files { id name mime }
  }
}

Query an element list

elements supports filtering, sorting, publication state, trash state and pagination.

query SharedText($first: Int!, $page: Int!) {
  elements(
    filter: {type: "text", lang: "en"}
    publish: DRAFT
    trashed: WITHOUT
    sort: [{column: NAME, order: ASC}]
    first: $first
    page: $page
  ) {
    data {
      id
      type
      name
      lang
      data
      latest { id published }
    }
    paginatorInfo {
      currentPage
      lastPage
      total
    }
  }
}

Filter elements

Effective ElementFilter fields

Field
Type
Matches
id
[ID!]
Any listed element UUID
type
String
Content element type
lang
String
ISO language code
editor
String
Last editor
any
String
Indexed text across name and structured data

The current resolver applies the fields listed above. Use any to search element names and structured data. Supported sort columns are ID, LANG, NAME, TYPE and EDITOR.

Create an element draft

Creating an element requires type and data. The available data fields depend on the selected content schema. Encode data as a JSON string for the MLL JSON scalar.

mutation AddElement($input: ElementInput!) {
  addElement(input: $input) {
    id
    type
    name
    lang
    data
    latest { id published }
  }
}
{
  "input": {
    "type": "text",
    "lang": "en",
    "name": "Shipping notice",
    "data": "{\"text\":\"Orders placed today ship on the next business day.\"}"
  }
}
{
  "data": {
    "addElement": {
      "id": "018f1f4c-65e7-742d-86cb-a775f00e3bb4",
      "type": "text",
      "name": "Shipping notice",
      "lang": "en",
      "data": "{\"text\":\"Orders placed today ship on the next business day.\"}",
      "latest": {
        "id": "0198d2df-0b9a-7974-8b69-6877d97fb3ed",
        "published": false
      }
    }
  }
}

File references contained in the decoded data document are discovered automatically. addElement does not accept a separate files argument. Element data is also returned as a JSON-encoded string, so parse it before use.

Reference an element from a page

Put a reference entry in the page’s decoded content array. refid is the shared element UUID; the entry itself still needs a stable content ID and group.

mutation AddElementReference(
  $page: ID!
  $latestId: ID!
  $content: JSON!
) {
  savePage(
    id: $page
    latestId: $latestId
    input: {content: $content}
  ) {
    id
    changed
    latest { id published }
    elements { id name type }
  }
}
{
  "page": "018f0f9d-83b3-7d69-a1b2-6f2db5e40c35",
  "latestId": "0198d2c8-b887-7a31-9e96-1082195f6bb0",
  "content": "[{\"id\":\"shipping-note\",\"type\":\"reference\",\"group\":\"main\",\"refid\":\"018f1f4c-65e7-742d-86cb-a775f00e3bb4\"}]"
}

Saving the page creates a page draft and attaches the referenced element to that version. Review publication state for both resources before expecting the reference on the public page.

Save with conflict detection

ElementInput is partial when saving. Pass the version ID you originally read as latestId; the returned changed value identifies conflicts if another editor saved first.

mutation SaveElement($id: ID!, $latestId: ID!, $input: ElementInput!) {
  saveElement(id: $id, latestId: $latestId, input: $input) {
    id
    name
    data
    changed
    latest { id published }
  }
}
{
  "id": "018f1f4c-65e7-742d-86cb-a775f00e3bb4",
  "latestId": "0198d2df-0b9a-7974-8b69-6877d97fb3ed",
  "input": {
    "name": "Updated shipping notice",
    "data": "{\"text\":\"Orders placed before 15:00 ship the same business day.\"}"
  }
}
{
  "data": {
    "saveElement": {
      "id": "018f1f4c-65e7-742d-86cb-a775f00e3bb4",
      "name": "Updated shipping notice",
      "data": "{\"text\":\"Orders placed before 15:00 ship the same business day.\"}",
      "changed": null,
      "latest": {
        "id": "0198d37b-c678-7073-ad58-d231cd8d38b4",
        "published": false
      }
    }
  }
}

Update several elements

bulkElement applies one partial input to as many as 1,000 shared elements and creates a draft for each successful item.

mutation RenameElements($ids: [ID!]!) {
  bulkElement(id: $ids, input: {lang: "en"}) {
    ids
    latest
    data
    failed
  }
}

Publish elements

Publish immediately by omitting at, or schedule the latest versions for a later DateTime.

mutation PublishElements($ids: [ID!]!, $at: DateTime) {
  pubElement(id: $ids, at: $at) {
    id
    name
    latest { id published publish_at }
  }
}

Trash, restore and purge

mutation TrashElements($ids: [ID!]!) {
  dropElement(id: $ids) { id name deleted_at }
}

mutation RestoreElements($ids: [ID!]!) {
  keepElement(id: $ids) { id name deleted_at }
}

mutation PurgeElements($ids: [ID!]!) {
  purgeElement(id: $ids) { id }
}

Trash is reversible; purge is permanent. Before purging an element, inspect bypages and byversions so you know where it is referenced.

Troubleshoot shared elements

Common element problems

Symptom
Likely cause
Resolution
Invalid JSON value
data was sent as a native object
Encode the element data once before sending it
Unknown element type
The active theme has no matching content schema
Inspect the registered theme schema and choose a supported type
Unknown files argument
An old addElement or saveElement signature was copied
Keep file references inside data; do not pass a separate files argument
changed is not null
Another editor saved after the supplied latestId
Re-read, review overwritten data and retry
Reference does not render
The refid is wrong, inaccessible or unpublished
Check the element UUID, view permission and publication state
Page still shows old content
Only a draft element was saved
Review it and publish the element version

Required permissions

Element permissions

Operation
Capability
element / elements
element:view
addElement
element:add
saveElement / bulkElement
element:save and element:view
dropElement
element:drop and element:view
keepElement
element:keep and element:view
purgeElement
element:purge and element:view
pubElement
element:publish and element:view