> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vellaro.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Compose

> Compose/modify a page's block-tree from an NL instruction (draft-only).



## OpenAPI

````yaml https://api.vellaro.io/openapi.json post /api/v1/admin/cms/ai/compose
openapi: 3.1.0
info:
  title: Vellaro API
  description: Vellaro 2026 — E-commerce API
  version: 0.1.0
servers:
  - url: https://api.vellaro.io
    description: Produzione
security: []
tags: []
paths:
  /api/v1/admin/cms/ai/compose:
    post:
      tags:
        - admin:cms-ai
      summary: Compose
      description: Compose/modify a page's block-tree from an NL instruction (draft-only).
      operationId: compose_api_v1_admin_cms_ai_compose_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ComposeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_ComposeResult_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    ComposeRequest:
      properties:
        instruction:
          type: string
          maxLength: 8000
          minLength: 1
          title: Instruction
        current_blocks:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Current Blocks
        page_type:
          type: string
          title: Page Type
          default: standard
        scope:
          type: string
          enum:
            - page
            - block
          title: Scope
          default: page
        brand:
          anyOf:
            - $ref: '#/components/schemas/BrandContext'
            - type: 'null'
        locales:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Locales
        default_locale:
          anyOf:
            - type: string
            - type: 'null'
          title: Default Locale
        max_retries:
          type: integer
          maximum: 5
          minimum: 0
          title: Max Retries
          default: 2
        page_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Page Id
        locale:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          title: Locale
      type: object
      required:
        - instruction
      title: ComposeRequest
      description: >-
        DTO for the admin HTTP layer (``cms_ai/router.py``).


        The engine itself takes explicit keyword arguments (DB-agnostic); this
        model

        only shapes the request envelope the router validates and translates
        into a

        ``compose_blocks(...)`` call.


        ANTI-INJECTION: ``brand``, ``locales``, ``default_locale`` and
        ``page_type``

        are resolved SERVER-SIDE from the tenant (active languages, store
        name/voice,

        the page's slug). They stay on the model for the engine's own re-use,
        but the

        router **ignores** any client-sent value for them — a caller can never
        steer

        the brand voice, spoof the active locales, or downgrade a legal page's
        review

        gate. Only ``instruction``, ``current_blocks``, ``scope``, ``page_id``
        and

        ``max_retries`` are honoured from the request body.
    ApiResponse_ComposeResult_:
      properties:
        data:
          anyOf:
            - $ref: '#/components/schemas/ComposeResult'
            - type: 'null'
        meta:
          anyOf:
            - $ref: '#/components/schemas/PaginationMeta'
            - type: 'null'
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
      type: object
      title: ApiResponse[ComposeResult]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    BrandContext:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Name
        voice:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Voice
        sector:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: Sector
      type: object
      title: BrandContext
      description: >-
        Brand signals that steer CONTENT and VOICE only — never styling.


        The F0 schema exposes no colour/style props, so brand can never leak
        into

        the design by construction; this only shapes the words the model writes.
    ComposeResult:
      properties:
        blocks:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Blocks
        status:
          type: string
          enum:
            - ok
            - failed
          title: Status
        explanation:
          type: string
          title: Explanation
          default: ''
        attempts:
          type: integer
          title: Attempts
          default: 0
        errors:
          items:
            type: string
          type: array
          title: Errors
        warnings:
          items:
            type: string
          type: array
          title: Warnings
        requires_human_review:
          type: boolean
          title: Requires Human Review
          default: false
        provider:
          anyOf:
            - type: string
            - type: 'null'
          title: Provider
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
      type: object
      required:
        - blocks
        - status
      title: ComposeResult
      description: 'The engine''s output: a VALID tree plus the "what I did" for chat/inline.'
    PaginationMeta:
      properties:
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total:
          type: integer
          title: Total
        total_pages:
          type: integer
          title: Total Pages
      type: object
      required:
        - page
        - page_size
        - total
        - total_pages
      title: PaginationMeta
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.