Entities API

query GetEntityModels {
  entityModels {
    key
    name
    pluralName
    description
    editorMode
    fields {
      key
      type
      label
      required
      isTranslatable
    }
    modes {
      records
      inline
      publicApi
    }
  }
}

query GetEntity($modelKey: String!, $id: ID!) {
  entity(modelKey: $modelKey, id: $id) {
    id
    modelKey
    naturalKey
    data
    translations
    metadata
    versionNumber
    publishedVersionNumber
    status
    createdAt
    updatedAt
  }
}

query GetPageWithAuthor {
  entity(modelKey: "page", id: "page_123", include: ["author", "category"]) {
    id
    data
    # author and category fields will be fully resolved
  }
}

query ListProducts($limit: Int, $offset: Int, $filters: [FilterInput!]) {
  entities(
    modelKey: "shopify-product"
    limit: $limit
    offset: $offset
    filters: $filters
    sort: { field: "createdAt", direction: DESC }
  ) {
    items {
      id
      naturalKey
      data
      status
    }
    total
    hasMore
  }
}

query SearchProducts($query: String!) {
  entities(
    modelKey: "shopify-product"
    search: $query
    limit: 20
  ) {
    items {
      id
      naturalKey
      data
    }
    total
  }
}

query FilteredProducts {
  entities(
    modelKey: "shopify-product"
    filters: [
      { field: "status", operator: EQ, value: "PUBLISHED" }
      { field: "data.price", operator: GTE, value: 100 }
      { field: "data.category", operator: IN, value: ["electronics", "gadgets"] }
    ]
  ) {
    items {
      id
      data
    }
  }
}

query GetVersionHistory {
  listEntityVersions(entityId: "page_123", limit: 10) {
    versions {
      id
      versionNumber
      state
      createdAt
      createdBy
      changeDescription
      name
      isCurrentDraft
      isActive
    }
    total
    hasMore
  }
}

mutation CreatePage($data: JSON!, $translations: JSON) {
  createEntity(
    modelKey: "page"
    data: $data
    translations: $translations
  ) {
    id
    naturalKey
    versionNumber
    status
  }
}

{
  "data": {
    "title": "About Us",
    "slug": "about",
    "content": "Welcome to our company..."
  },
  "translations": {
    "ja-JP": {
      "title": "会社概要",
      "content": "会社へようこそ..."
    }
  }
}

mutation UpdatePage($id: ID!, $data: JSON!) {
  updateEntity(
    modelKey: "page"
    id: $id
    data: $data
  ) {
    id
    versionNumber
    status
  }
}

mutation PublishPage($id: ID!) {
  publishEntity(modelKey: "page", id: $id) {
    id
    status
    publishedVersionNumber
  }
}

mutation UnpublishPage($id: ID!) {
  unpublishEntity(modelKey: "page", id: $id) {
    id
    status
  }
}

mutation DeletePage($id: ID!) {
  deleteEntity(modelKey: "page", id: $id) {
    success
    message
  }
}

mutation CreatePages($items: [CreateEntityInput!]!) {
  createEntities(modelKey: "page", items: $items) {
    results {
      success
      record {
        id
        naturalKey
      }
      error
      errorCode
    }
    successCount
    failureCount
  }
}

{
  "items": [
    { "data": { "title": "Page 1", "slug": "page-1" } },
    { "data": { "title": "Page 2", "slug": "page-2" } },
    { "data": { "title": "Page 3", "slug": "page-3" } }
  ]
}

mutation UpdatePages($items: [UpdateEntityInput!]!) {
  updateEntities(modelKey: "page", items: $items) {
    results {
      success
      record {
        id
        versionNumber
      }
      error
      errorCode
    }
    successCount
    failureCount
  }
}

{
  "items": [
    { "id": "page_1", "data": { "title": "Updated Page 1" } },
    { "id": "page_2", "data": { "title": "Updated Page 2" } }
  ]
}

const { data } = await client.mutate({
  mutation: CREATE_ENTITIES,
  variables: { items }
});
 
const { results, successCount, failureCount } = data.createEntities;
 
// Handle successes
const created = results.filter(r => r.success).map(r => r.record);
 
// Handle failures
const errors = results
  .filter(r => !r.success)
  .map((r, i) => ({ index: i, error: r.error, code: r.errorCode }));
 
if (errors.length > 0) {
  console.error(`${failureCount} items failed:`, errors);
}

type EntityRecord {
  id: ID!
  modelKey: String!
  naturalKey: String
  data: JSON!
  translations: JSON
  metadata: JSON
  versionNumber: Int!
  publishedVersionNumber: Int
  status: EntityStatus!
  createdAt: DateTime!
  updatedAt: DateTime!
}

enum EntityStatus {
  DRAFT      # Has unpublished changes
  PUBLISHED  # Published and live
  ARCHIVED   # Soft deleted
}

enum VersionState {
  ACTIVE    # Published version (default)
  LATEST    # Latest draft
  SPECIFIC  # Use with versionId/versionNumber
}

query GetPageBySlug($slug: String!) {
  entities(
    modelKey: "page"
    filters: [{ field: "naturalKey", operator: EQ, value: $slug }]
    limit: 1
  ) {
    items {
      id
      data
    }
  }
}

query ListPublishedProducts {
  entities(
    modelKey: "shopify-product"
    filters: [{ field: "status", operator: EQ, value: "PUBLISHED" }]
    sort: { field: "updatedAt", direction: DESC }
    limit: 20
  ) {
    items {
      id
      naturalKey
      data
      metadata
    }
    total
  }
}

mutation CreateAndPublish($data: JSON!) {
  # Step 1: Create
  created: createEntity(modelKey: "page", data: $data) {
    id
  }
}
 
# Then in a second request:
mutation Publish($id: ID!) {
  publishEntity(modelKey: "page", id: $id) {
    id
    status
  }
}