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

# Create a block

> Creates a new block in an asset at root level or under a parent block.

Create a new block by providing a block payload. Optionally set `parentId` and `position`.


## OpenAPI

````yaml /openapi.yaml post /assets/{assetId}/blocks
openapi: 3.1.0
info:
  title: Versuno Public API
  description: >
    The Versuno Public API lets you manage AI assets, projects, and version
    history programmatically.


    All endpoints except key management require a Bearer API key in the
    `Authorization` header.

    API keys are formatted as
    `uk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
  version: 1.0.0
  contact:
    email: support@versuno.ai
servers:
  - url: https://versuno.ai/api/public
    description: Production
  - url: http://localhost:3000/api/public
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Verify API key validity and retrieve the caller's identity.
  - name: Teams
    description: Teams the authenticated user owns or is an active member of.
  - name: Assets
    description: AI assets — prompts, personas, contexts, system prompts, and skills.
  - name: Asset Trash
    description: Single-asset soft-delete, restore, and permanent delete lifecycle.
  - name: Bulk Asset Trash
    description: Bulk trash operations across multiple assets at once.
  - name: Projects
    description: Project folders for organising assets and teams.
  - name: Project Trash
    description: Project trash lifecycle — trashing deletes the entire subtree.
  - name: Versioning
    description: Full-snapshot version history with non-destructive revert support.
  - name: Public Brains
    description: >-
      Graph-based knowledge structures composed of containers (folders/groups)
      and nodes (content items). Read the graph, or run semantic RAG queries
      against it.
  - name: Memory
    description: >-
      The universal agent-memory layer. Capture coding-agent memory, recall it
      semantically, and resolve contradictions. Capture-only, scoped to your API
      key's account.
  - name: Key Management
    description: >-
      Create, update, and delete API keys. These endpoints do not require a
      Bearer token.
paths:
  /assets/{assetId}/blocks:
    post:
      tags:
        - Assets
      summary: Create a block
      description: Creates a new block in an asset at root level or under a parent block.
      operationId: createAssetBlock
      parameters:
        - name: assetId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: assetType
          in: query
          required: false
          description: >-
            Optional type guard. If supplied, it must match the asset's actual
            type.
          schema:
            type: string
            enum:
              - prompt
              - persona
              - context
              - system_prompt
              - skill
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - block
              properties:
                block:
                  type: object
                  required:
                    - type
                  properties:
                    id:
                      type: string
                      description: Optional. If omitted, server generates one.
                    type:
                      type: string
                      enum:
                        - paragraph
                        - heading
                        - code
                        - divider
                        - bullet_list
                        - ordered_list
                        - todo_list
                        - toggle
                        - quote
                        - callout
                        - table
                        - block_snippet
                        - block_ref
                        - asset_ref
                    content:
                      anyOf:
                        - type: string
                        - type: 'null'
                    inline:
                      type: array
                      items:
                        type: object
                        additionalProperties: true
                    meta:
                      type: object
                      additionalProperties: true
                parentId:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Target parent block ID. Null means root level.
                position:
                  type: integer
                  minimum: 0
                  description: Insert position among siblings.
            example:
              block:
                type: paragraph
                content: New block text
                meta: {}
              parentId: null
              position: 0
      responses:
        '201':
          description: Block created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  assetId:
                    type: string
                    format: uuid
                  block:
                    $ref: '#/components/schemas/Block'
                  content:
                    type: string
                  contentBlocks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Block'
        '400':
          description: Invalid UUID, invalid body, or bad `assetType`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Asset or parent block not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '409':
          description: Block ID conflict.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error409'
components:
  schemas:
    Block:
      type: object
      description: A single editor block in an asset's structured content tree.
      required:
        - id
        - type
        - meta
      properties:
        id:
          type: string
          description: Stable block identifier.
          example: b_35effee2-0c97-463b-9a0a-8973eca1b4da
        type:
          type: string
          enum:
            - paragraph
            - heading
            - code
            - divider
            - bullet_list
            - ordered_list
            - todo_list
            - toggle
            - quote
            - callout
            - table
            - block_snippet
            - block_ref
            - asset_ref
          example: paragraph
        content:
          anyOf:
            - type: string
            - type: 'null'
          description: Optional block textual content.
          example: This block was updated
        inline:
          type: array
          description: Optional inline span model.
          items:
            type: object
            additionalProperties: true
        meta:
          type: object
          additionalProperties: true
          description: Block metadata for type-specific attributes.
          example: {}
        children:
          type: array
          items:
            $ref: '#/components/schemas/Block'
    Error400:
      type: object
      properties:
        error:
          type: string
          example: 'Wrong data: assetType is required'
    Error401:
      type: object
      properties:
        error:
          type: string
          example: Invalid API key
    Error403:
      type: object
      properties:
        error:
          type: string
          example: Forbidden
    Error404:
      type: object
      properties:
        error:
          type: string
          example: Not found
    Error409:
      type: object
      properties:
        error:
          type: string
          example: Asset is already in trash
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Versuno API key. Must be prefixed with `Bearer`. Format: `Bearer
        uk_live_...`
      x-default: Bearer uk_live_your_api_key_here

````