API Reference GraphQL APIMutation API Guidelines

Mutation API Guidelines

Learn how to create, update, and delete content in BaseHub using the Mutation API with detailed examples and best practices.

The Mutation API allows you to programmatically create, update, and delete content in your BaseHub repository. This guide covers all operation types with detailed examples and best practices.

Operation Types

You can perform three types of operations:

create: Add new blocks
update: Modify existing blocks
delete: Remove blocks

Create Operations

Create a Text Block

{
  "parentId": "<layout-block-id>",
  "data": [{
    "type": "text",
    "title": "Hero Title",
    "value": "A purpose-built tool for planning and building products",
    "isRequired": true
  }]
}

In general, you'll want to mark all blocks as required.

Create a Component Block

{
  "parentId": "<layout-block-id>",
  "data": [{
    "transactionId": "cta-component",
    "type": "component",
    "title": "CTA",
    "hidden": true,
    "value": [
      {
        "type": "text",
        "title": "Label",
        "value": "",
        "isRequired": true
      },
      {
        "type": "text",
        "title": "Href",
        "value": "",
        "isRequired": true
      },
      {
        "type": "select",
        "title": "Variant",
        "value": ["primary"],
        "acceptedValues": ["primary", "secondary", "ghost"],
        "multiple": false,
        "isRequired": true,
        "description": "We'll style the button based on the variant"
      }
    ]
  }]
}

Notice how we're not using children for nesting, but rather, we just use the value field, which in the case of layout blocks, accept an array of blocks.

Create an Instance Block

{
  "parentId": "<layout-block-id>",
  "data": [{
    "type": "instance",
    "title": "Sign Up Button",
    "mainComponentId": "cta-component",
    "value": {
      "label": {
        "type": "text",
        "value": "Sign Up for Free"
      },
      "href": {
        "type": "text",
        "value": "/sign-up"
      },
      "variant": {
        "type": "select",
        "value": ["primary"]
      }
    }
  }]
}

Key points about instances:

We use mainComponentId to reference the component
The instance's value field is an object defining values via their API Names

Create a Collection Block

{
  "parentId": "<layout-block-id>",
  "data": [{
    "type": "collection",
    "title": "Authors",
    "template": [
      {
        "type": "text",
        "title": "Role",
        "isRequired": true
      },
      {
        "type": "media",
        "title": "Avatar",
        "isRequired": true
      }
    ],
    "rows": [
      {
        "type": "instance",
        "title": "Frank Ocean",
        "value": {
          "role": {
            "type": "text",
            "value": "Musician"
          },
          "avatar": {
            "type": "media",
            "value": {
              "url": "https://assets.basehub.com/example.jpg",
              "fileName": "frank-ocean-avatar.jpg",
              "altText": "Frank Ocean"
            }
          }
        }
      }
    ]
  }]
}

Update Operations

Update a Text Block

{
  "data": [{
    "id": "<block-id>",
    "title": "Updated Title",
    "value": {
      "role": {
        "type": "text",
        "value": "Producer and Podcast Host"
      }
    }
  }]
}

Update with Variants

{
  "data": [{
    "id": "<block-id>",
    "value": {
      "heroTitle": {
        "type": "text",
        "variantOverrides": {
          "language-es": {
            "value": "Finalmente, un CMS que se mueve tan rápido como tú."
          }
        }
      }
    }
  }]
}

Primitive Block Value Formats

Here are all primitive block types and their corresponding value formats:

text: { "type": "text", "value": "string content" }
number: { "type": "number", "value": 123 }
boolean: { "type": "boolean", "value": true }
date: { "type": "date", "value": "2025-03-07" }
color: { "type": "color", "value": "#RRGGBB" }
media: { "type": "media", "value": { "url": "...", "fileName": "...", "altText": "..." } }
reference (single): { "type": "reference", "value": "block-id" }
reference (multiple): { "type": "reference", "multiple": true, "value": ["block-id-1", "block-id-2"] }
event: { "type": "event", "value": { "schema": {}, "view": 'table' | 'chart' } }

Rich Text Format

{
  "type": "rich-text",
  "value": {
    "format": "json",
    "value": [...] // ProseMirror-compatible JSON
  }
}

Code Snippet Format

{
  "type": "code-snippet",
  "value": {
    "code": "const hello = 'world';",
    "language": "javascript"
  }
}

Common Mutation API Errors

Rich Text Formatting Mismatch

Passing format: "json" with a markdown string will result in an error. You should pass a Rich Text JSON object instead.