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

# Insert a block

> Post a new block of one of your types as a message from your app, outside any interaction.

> Reintersect apps are in developer preview. Names and limits can still change before general
> release.

Inserts a block of one of your app's types in a message authored by your app. Reintersect validates
the props against the block's props schema, sends your app a `block.insert` delivery for the initial
state and tree, posts the message, and sends `block.created`. The block has no creator, so
`audience="creator"` parts fall back to admins.

Authenticate with an install token that has the `blocks:write` scope. The target must be within the install's
[reach](/api-reference/overview#reach).

## Body

Send exactly one of `conversationId`, `replyTo` and `circleId`. They place the message the same way
as for [replies](/api-reference/replies/create).

| Field | Type | Required | Description |
| - | - | - | - |
| `type` | `string` | Yes | The block type, as declared with `defineBlock({ type })`. |
| `props` | `object` | Yes | Must match the block's props schema; at most 16 KB as JSON. |
| `conversationId` | `string` | One of | Post in this conversation. |
| `replyTo` | `string` | One of | Reply to this message. |
| `circleId` | `string` | One of | Post in this circle's chat. Only for circles that use chat. |

## Response

`200` with the block:

| Field | Type | Description |
| - | - | - |
| `id` | `string` | The block id. |
| `appId` | `string` | Your app's id. |
| `type` | `string` | The block type. |
| `props` | `object` | The props the block was created with. |
| `state` | `object` | The current state. |
| `version` | `number` | Increases with every change. Pass it as `expectedVersion`. |
| `final` | `boolean` | Whether the block is locked. |
| `summary` | `string` | The block's current summary. |
| `circleId` | `string \| null` | The circle the block is in. |
| `conversationId` | `string \| null` | The conversation the block is in, or `null` for a chat message not filed in one. |
| `replyId` | `string \| null` | The reply that holds the block, or `null` in the opening post. |
| `createdAt`, `updatedAt` | `string` | ISO 8601 timestamps. |

## Errors

| `_tag` | Status | Cause |
| - | - | - |
| `ReintersectAppScopeMissingError` | 403 | The install lacks `blocks:write`. |
| `ReintersectAppBlockTypeUnknownError` | 422 | The installed version has no block of this type. |
| `ReintersectAppBlockPropsInvalidError` | 422 | The props don't match the schema. |
| `ReintersectAppResponseInvalidError` | 502 | Your app's `block.insert` answer was invalid or its tree failed validation. |
| `ReintersectApiConversationNotFoundError` | 404 | No such conversation in the install's reach. |
| `ReintersectApiReplyNotFoundError` | 404 | No such message in the install's reach. |
| `ReintersectAppCircleNotFoundError` | 404 | No such circle in the install's reach, or the circle doesn't use chat. `circleIds` holds the circle id you sent. |
| `ReintersectApiReplyNestingLimitError` | 422 | On a board, the reply is already nested as deep as replies go. |

## Example

```bash theme={null}
curl -X POST https://api.reintersect.com/v0/blocks \
  -H "authorization: Bearer $INSTALL_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "type": "task", "conversationId": "conv_123", "props": { "id": "TASK-42", "title": "Ship the checklist" } }'
```

With the SDK, call `reintersect.blocks.insert(TaskBlock, { conversationId, props })`, or pass `replyTo`
or `circleId` instead of `conversationId`.


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