---
title: "Agrega un bloque nuevo (o lo inserta después de after_block_id)"
method: POST
path: "/items/{itemId}/content/blocks"
tags: ["Items"]
---

# Agrega un bloque nuevo (o lo inserta después de after_block_id)

`POST /items/{itemId}/content/blocks`

## Request

- Base URL: `https://api.met.meteor.com.co/api/v1`
- URL: `https://api.met.meteor.com.co/api/v1/items/{itemId}/content/blocks`
- Auth: one of:
  - `bearer` (a scheme the document does not define)
  - HTTP bearer

Agrega un bloque al final, o justo después de otro si pasas la referencia. Es la forma incremental de construir contenido sin reenviar todo el documento.

## Path parameters

- `itemId` number, required

## Request body

- CreateBlockDto
  - `after_block_id` string, uuid: Si se pasa, el bloque se inserta inmediatamente despues del bloque con este id. Si no, se agrega al final.
  - `data` object, required: Cuerpo del bloque. Forma depende de type (ver BlockValidatorService).
  - `id` string, uuid: ID del bloque generado por el cliente para optimistic updates. Cuando el frontend hace edicion tipo Notion, necesita conocer el id antes de que el servidor responda (focus, sync). Si se omite, el backend genera uno.
  - `type` 'text' | 'heading' | 'image' | 'task' | 'file' | 'collection_ref' | 'item_ref' | 'contact_ref' | 'web_fields_ref', required

## Response `201`

- object: Sobre en el que viaja toda respuesta correcta de la API. El recurso está en `data`. Los SDKs oficiales lo desenvuelven por ti; un cliente hecho a mano tiene que leer `.data`.
  - `success` true, required: Siempre `true` en una respuesta 2xx.
  - `data` ContentBlockResponseDto, required
    - `created_at` string, required
    - `data` object, required: Contenido del bloque. **La forma depende de `type`** — `text` trae `html`, `image` trae `storage_path`, `task` trae `task_id`, y las referencias traen el id de lo que apuntan. Al **leer**, cada bloque que referencia otra entidad trae además `data.__hydrated` con su estado actual (nombre, estado, contadores) para pintarlo sin un fetch extra. Si la entidad fue borrada, llega `__hydrated: { deleted: true }`. Ese bloque es **solo de lectura**: no se manda de vuelta al escribir.
    - `id` string, required: UUID v4. Lo genera el backend al crear, salvo que el cliente mande el suyo.
    - `type` 'text' | 'heading' | 'image' | 'task' | 'file' | 'collection_ref' | 'item_ref' | 'contact_ref' | 'web_fields_ref', required
    - `updated_at` string, required

## Other responses

- `400`: La request no es válida: un campo no pasa validación, falta un parámetro requerido o el recurso no admite la transición solicitada.
- `401`: API key ausente, inválida, revocada o expirada — o el workspace está bloqueado.
- `403`: La key está autenticada pero no puede ejecutar esta operación: scope faltante, capacidad deshabilitada, modo test restringido o recurso fuera de su cartera.
- `404`: El recurso no existe o no está disponible dentro del alcance de la key. No revela la existencia de recursos de otros tenants.
- `409`: La operación entra en conflicto con el estado actual o con un Idempotency-Key en uso. No reintentes con el mismo key y un body distinto.
- `429`: Se superó el límite por minuto de la key o la cuota del plan. Respeta `Retry-After`; el SDK ya reintenta solo.
- `500`: Error del servidor o del Met que ejecutaba. El SDK reintenta los 5xx con backoff.

---

[API](https://skmtc.dev/meteor/apis/met-public-api.md) · [All operations](https://skmtc.dev/meteor/apis/met-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/meteor/apis/met-public-api/revisions/5d9ca294295c?raw)