> ## 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.
# Apply block operations
> Applies structural block transforms using the unified turn_into command.
Use this endpoint for structural transforms that rewrite the block tree.
## Supported operations
Only one operation is supported: `turn_into`.
Supported `turnInto` values:
* `paragraph`
* `heading1`, `heading2`, `heading3`
* `codeBlock`
* `quote`
* `toggleH1`, `toggleH2`, `toggleH3`, `toggle`
* `callout`
* `bulletList`, `orderedList`, `taskList`
Use `PATCH /assets/{assetId}/blocks` for field updates only (`content`, `inline`, `meta`).
## Code examples
```bash cURL theme={null}
curl -X POST "https://versuno.ai/api/public/assets//blocks/operations" \
-H "Authorization: Bearer uk_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"operations": [
{
"op": "turn_into",
"targetBlockId": "b_35effee2-0c97-463b-9a0a-8973eca1b4da",
"turnInto": "quote"
}
]
}'
```
```javascript Node.js theme={null}
const res = await fetch(
"https://versuno.ai/api/public/assets//blocks/operations",
{
method: "POST",
headers: {
Authorization: "Bearer uk_live_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
operations: [
{
op: "turn_into",
targetBlockId: "b_35effee2-0c97-463b-9a0a-8973eca1b4da",
turnInto: "toggleH2",
},
],
}),
}
);
const data = await res.json();
```
```python Python theme={null}
import requests
response = requests.post(
"https://versuno.ai/api/public/assets//blocks/operations",
headers={
"Authorization": "Bearer uk_live_your_api_key_here",
"Content-Type": "application/json",
},
json={
"operations": [
{
"op": "turn_into",
"targetBlockId": "b_35effee2-0c97-463b-9a0a-8973eca1b4da",
"turnInto": "callout",
}
]
},
)
result = response.json()
```
## OpenAPI
````yaml openapi.yaml POST /assets/{assetId}/blocks/operations
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/operations:
post:
tags:
- Assets
summary: Apply block operations
description: Applies structural block transforms using the unified turn_into command.
operationId: applyBlockOperations
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:
- operations
properties:
operations:
type: array
minItems: 1
items:
type: object
required:
- op
- targetBlockId
- turnInto
properties:
op:
type: string
enum:
- turn_into
targetBlockId:
type: string
turnInto:
type: string
enum:
- paragraph
- heading1
- heading2
- heading3
- codeBlock
- quote
- toggleH1
- toggleH2
- toggleH3
- toggle
- callout
- bulletList
- orderedList
- taskList
example:
operations:
- op: turn_into
targetBlockId: b_35effee2-0c97-463b-9a0a-8973eca1b4da
turnInto: quote
- op: turn_into
targetBlockId: b_74f0ee4e-59c3-4593-9ac7-7b0f5ddf359a
turnInto: heading2
responses:
'200':
description: Operations applied and full updated block tree returned.
content:
application/json:
schema:
type: object
properties:
assetId:
type: string
format: uuid
appliedOperations:
type: array
items:
type: object
properties:
op:
type: string
targetBlockId:
type: string
turnInto:
type: string
contentBlocks:
type: array
items:
$ref: '#/components/schemas/Block'
'400':
description: Invalid UUID, invalid operation payload, 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 target 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
````