**API versions** · [V2 (Latest)](/integrations/v2/docs?lang=en) · **V1**

> **This API version is obsolete.** Use the latest version for new integrations. [View the current documentation](/integrations/v2/docs?lang=en)

# Content Blocks

OpenAPI 3.0.3 · API 1.0.0

```json
[
  {
    "url": "https://api.unisoft.world/integrations/v1",
    "description": "API"
  }
]
```

Reusable AI content blocks — standalone HTML fragments rendered wherever their id is referenced (e.g. the tourism home page via the travel config `homepage.aiContentBlockId`, or a multi-session event group intro). Send PLAIN HTML; the server adds the data-i18n keys (see ContentBlockContentInput for the HTML authoring rules). Scopes: `content_blocks:read`/`content_blocks:write`.

## Operations

## GET /content-blocks

List content blocks

`list_content_blocks`

Required scope: `content_blocks:read`. Lists the org's content blocks (light fields). Paginated. To discover WHICH block backs a given spot, read its referencing config — e.g. the travel `homepage.aiContentBlockId`.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "content_blocks:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "limit",
  "in": "query",
  "schema": {
    "type": "integer",
    "minimum": 1,
    "maximum": 200,
    "default": 50
  },
  "description": "Number of results per page"
}
```

```json
{
  "name": "cursor",
  "in": "query",
  "schema": {
    "type": "string"
  },
  "description": "Opaque cursor returned by the previous request"
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContentBlock"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      }
    }
  }
}
```

#### HTTP 401

```json
{
  "description": "ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 403

```json
{
  "description": "INSUFFICIENT_SCOPE",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "INSUFFICIENT_SCOPE"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "content_blocks:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## GET /content-blocks/{id}

Get a content block

`get_content_block`

Required scope: `content_blocks:read`. Full block incl. `html`, `i18n` and `mainLang`.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "content_blocks:read",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Content block id — any stable string you choose (a UUID is recommended; generate one with GET /utils/uuid). PUT /content-blocks/{id}/content upserts, so this id need not pre-exist."
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "$ref": "#/components/schemas/ContentBlock"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "content_blocks:read",
  "x-unisoft-mcp": {
    "category": "read",
    "readOnly": true,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## PUT /content-blocks/{id}/content

Set the HTML content of a block

`set_content_block_content`

Required scope: `content_blocks:write`. Sets the block HTML; the server injects data-i18n keys and merges translations (see ContentBlockContentInput for the mandatory HTML authoring rules). Upserts: if the id does not exist yet the block is created, so you can write a block then link it from a travel homepage (`PATCH /travel/{travelId}/config/homepage` with `aiContentBlockId`) or an event group.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "content_blocks:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Content block id — any stable string you choose (a UUID is recommended; generate one with GET /utils/uuid). PUT /content-blocks/{id}/content upserts, so this id need not pre-exist."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContentBlockContentInput"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "content_blocks:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## POST /content-blocks/{id}/translations

Set content block translations

`set_content_block_translations`

Required scope: `content_blocks:write`. Updates translations of existing data-i18n keys for one language. Does not change the HTML.

### Authentication

```json
[
  {
    "bearerAuth": []
  },
  {
    "apiKeyHeader": []
  }
]
```

### Required permissions

```json
{
  "accepted": "content_blocks:write",
  "additional": []
}
```

### Parameters

```json
{
  "name": "id",
  "in": "path",
  "required": true,
  "schema": {
    "type": "string"
  },
  "description": "Content block id — any stable string you choose (a UUID is recommended; generate one with GET /utils/uuid). PUT /content-blocks/{id}/content upserts, so this id need not pre-exist."
}
```

### Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/ContentBlockTranslationsInput"
      }
    }
  }
}
```

### Responses

#### HTTP 200

```json
{
  "description": "OK",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          }
        }
      }
    }
  }
}
```

#### HTTP 400

```json
{
  "description": "VALIDATION_ERROR",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "VALIDATION_ERROR"
          }
        }
      }
    }
  }
}
```

#### HTTP 404

```json
{
  "description": "NOT_FOUND",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string",
            "example": "NOT_FOUND"
          }
        }
      }
    }
  }
}
```

### OpenAPI

```json
{
  "x-unisoft-scope": "content_blocks:write",
  "x-unisoft-mcp": {
    "category": "update",
    "readOnly": false,
    "destructive": false,
    "idempotent": true,
    "warn": false
  }
}
```

## Schemas

```json
{
  "components": {
    "parameters": {
      "LimitParam": {
        "name": "limit",
        "in": "query",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 200,
          "default": 50
        },
        "description": "Number of results per page"
      },
      "CursorParam": {
        "name": "cursor",
        "in": "query",
        "schema": {
          "type": "string"
        },
        "description": "Opaque cursor returned by the previous request"
      },
      "ContentBlockIdParam": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Content block id — any stable string you choose (a UUID is recommended; generate one with GET /utils/uuid). PUT /content-blocks/{id}/content upserts, so this id need not pre-exist."
      }
    },
    "schemas": {
      "ContentBlock": {
        "type": "object",
        "description": "A reusable AI content block: a standalone HTML fragment rendered on the public site wherever its `id` is referenced (e.g. the tourism home page via the travel config `homepage.aiContentBlockId`, or a multi-session event group intro). Carries the HTML with `data-i18n` keys plus the `i18n` dictionary of their translations.",
        "properties": {
          "id": {
            "type": "string"
          },
          "organisation": {
            "type": "string"
          },
          "html": {
            "type": "string",
            "description": "The block HTML fragment (with data-i18n attributes)."
          },
          "mainLang": {
            "type": "string",
            "nullable": true,
            "description": "Default language the HTML is written in."
          },
          "i18n": {
            "type": "object",
            "description": "Translations: { lang: { i18nKey: value } } for the data-i18n keys in the HTML.",
            "additionalProperties": true
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Asset filenames referenced by the HTML."
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "datetime": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "nextCursor": {
            "type": "string",
            "nullable": true
          },
          "hasMore": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          }
        }
      },
      "ContentBlockContentInput": {
        "type": "object",
        "description": "HTML content for an AI content block. Send PLAIN HTML — you do NOT manage translation keys yourself:\nthe server injects a `data-i18n=\"<key>\"` attribute on every translatable text node that lacks one\n(and `data-i18n-alt`/`-title`/`-placeholder`/`-aria-label` for those attributes), auto-generating keys\nlike `auto_1`. The text in `mainLang` becomes the reference dictionary; existing translations for other\nlanguages are preserved and stale keys pruned (so KEEP existing data-i18n keys when re-editing).\nThe block is rendered wherever its id is referenced (e.g. the tourism home page).\n\nAUTHORING RULES the HTML MUST follow (same as the in-app AI editor, since there is no editor to enforce them here):\n• Output a FRAGMENT only — NO <!DOCTYPE>, <html>, <head> or <body>; start directly with <section>/<div>/<article>.\n• Wrap everything in a centred container: max-width:1200px; margin:0 auto; lateral padding 24px desktop / 16px mobile.\n• Prefix ALL CSS classes with `.aicb-` (e.g. .aicb-hero, .aicb-card) to avoid clashing with the host page.\n• NEVER use the viewport height units vh/vmin/vmax (the block renders in an auto-height iframe → infinite loop);\n  use px/rem or min-height:600px for hero sections. vw (width) is allowed.\n• Put <style> at the START of the fragment and any <script> at the END. CSS vanilla only (flexbox/grid/variables/@keyframes).\n• Fonts: Google Fonts via @import inside <style> (Inter, Plus Jakarta Sans, DM Sans). Icons: Lucide via CDN\n  (<script src=\"https://unpkg.com/lucide@latest\"></script> + lucide.createIcons(), <i data-lucide=\"...\">).\n• This is a JEWISH community site: NEVER introduce a symbol/icon/emoji of another religion (Lucide `church`/`cross`…,\n  emojis ✝️⛪☦️☪️🕌🛕☸️🔯). Jewish symbols (✡️ 🕎) and neutral icons/emojis are fine.\n• Avoid white text on a coloured card (readability).",
        "required": [
          "html"
        ],
        "properties": {
          "html": {
            "type": "string",
            "description": "The block HTML fragment. data-i18n keys are added automatically. Follow the authoring rules above."
          },
          "mainLang": {
            "type": "string",
            "description": "Language the HTML is written in (e.g. \"fr\"). Defaults to the block's current mainLang or the org default."
          },
          "assets": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional asset filenames referenced by the HTML."
          }
        }
      },
      "ContentBlockTranslationsInput": {
        "type": "object",
        "description": "Translations for one language of a content block's existing data-i18n keys. Does not change the HTML. Read the block (its `i18n` + the `data-i18n` keys in `html`) to discover the keys.",
        "required": [
          "lang",
          "dict"
        ],
        "properties": {
          "lang": {
            "type": "string",
            "description": "Target language code (e.g. \"en\", \"he\")."
          },
          "dict": {
            "type": "object",
            "description": "{ i18nKey: translatedValue }.",
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Format: `ke_live_xxx`"
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  }
}
```
