Edit content blocks

Content blocks make up many records. The standard create and update endpoints cannot change blocks: they reject the blocks, theme, and themeSettings fields with a 422. To edit blocks, use the dedicated endpoint, which applies a list of operations to one record:

PATCH /partners/{version}/{tenant}/{collection}/{id}/blocks

Supported collections: pages, blogs, posts, events, people, works, venues, series, seasons, organizations.

How a block looks

A block is { id, type, value }. The value holds the fields for the block in the same flattened shape you receive when reading the record. What you read back is what you send.

{
  "id": "hero_1",
  "type": "hero",
  "value": {
    "heading": "Spring season",
    "body_html": "<p>Now on sale.</p>"
  }
}

Inside value:

• Rich text accepts either a <field>_html property (an HTML string) or structured rich-text content for the field. The <field>_html form works at the top level and inside array/group sub-fields, and matches the shape reads return.
• Links and media: set them by id. Pass the id of the page, event, image, or file you want to reference.
• Ambiguous links that could point to more than one kind of record take { "relationTo": "events", "value": "evt_123" }.

Operations

Send an operations array. Operations apply in order. The endpoint always targets blocks by id, not by position.

New blocks may include an id. Omit it to let the API assign one.

Avoid overwriting newer changes

ifUpdatedAt guards against overwriting edits made after you last read the record:

Operations are all-or-nothing: if any operation is invalid, the API applies none of them.

Example

curl -X PATCH \
  -H "Authorization: users API-Key a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "draft": true,
    "ifUpdatedAt": "2026-06-04T10:12:00.000Z",
    "operations": [
      { "op": "update", "blockId": "hero_1", "value": { "heading": "Updated heading" } },
      { "op": "insertAfter", "blockId": "hero_1", "block": { "type": "rich-text", "value": { "body_html": "<p>New section.</p>" } } }
    ]
  }' \
  "https://api.basker.app/partners/2026-02/remarkable-theatre/pages/page_123/blocks"

A successful request returns 200 with a summary of what the API applied and the updated record:

{
  "versionTarget": "draft",
  "operations": [
    { "op": "update", "status": "applied", "blockId": "hero_1" },
    { "op": "insertAfter", "status": "applied", "blockId": "hero_1", "insertedBlockId": "000000000000000000000002" }
  ],
  "document": { "id": "page_123", "slug": "home" }
}

The same request shape works for any supported collection: swap pages for events, people, blogs, and so on.

When a request is rejected

See Status codes and Error responses for the full list and response shape.

Theme settings

Theme settings come in two scopes. Both use a field model with set (keys to change) and unset (keys to clear). Both also use the same draft: true and ifUpdatedAt safety as block editing:

{
  "draft": true,
  "ifUpdatedAt": "2026-06-04T10:12:00.000Z",
  "set": { "primaryColor": "#1d4ed8" },
  "unset": ["legacyBanner"]
}

Site-wide theme settings

Global theme settings apply across the whole site, independent of any one record:

PATCH /partners/{version}/{tenant}/theme/settings

It always targets the theme selected for the tenant: there is no id to pass. See Update Theme Settings.

Per-record theme settings

A single record can also carry its own theme settings, for example a page that uses its template. Edit one record with:

PATCH /partners/{version}/{tenant}/{collection}/{id}/theme-settings

The allowed keys come from that record's template: its own selection, or the collection default if it has none. It supports the same collections as block editing (pages, blogs, posts, events, people, works, venues, series, seasons, organizations). See Update record theme settings. Every supported collection has an equivalent reference page.

The API rejects unknown setting keys with 422 in both scopes.

Next steps

• Mutate document blocks: the block endpoint reference. Every supported collection has an equivalent entry.
• Update Theme Settings: edit the theme's site-wide settings.
• Update record theme settings: edit a single record's theme settings.
• Bulk update configured fields: preview and apply one configured-field change across matching records.
• Response format: how block fields are flattened in responses.
• Field selection: trim what a read returns.