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

# Blocks

> Blocks are the content units inside a group. Type is fixed at creation.

## Endpoints

| Method   | Path                                                 | Description            |
| -------- | ---------------------------------------------------- | ---------------------- |
| `POST`   | `/api/v2/blocks`                                     | Create blocks          |
| `GET`    | `/api/v2/blocks?pageId={page_id}&groupId={group_id}` | List blocks in a group |
| `PATCH`  | `/api/v2/blocks/{block_id}`                          | Update a block         |
| `DELETE` | `/api/v2/blocks/{block_id}?pageId={page_id}`         | Delete a block         |

<Note>
  Block type is **immutable** after creation. To change a block's type, delete it and create a new one.
</Note>

## Block types

| Type          | Use it for         | Content field                    |
| ------------- | ------------------ | -------------------------------- |
| `text`        | Rich text          | `content` — accepts **Markdown** |
| `image`       | Images             | `url` — auto-stored in Flowla S3 |
| `embed`       | Web pages, iframes | `url`                            |
| `link`        | Clickable URLs     | `url`                            |
| `pdf`         | PDF documents      | `url` — auto-stored in Flowla S3 |
| `action-plan` | Task checklists    | *(no extra fields)*              |

***

## Create blocks

`POST /api/v2/blocks`

Blocks are organized into **columns**. Each element of `columns` is a vertical stack of blocks; multiple elements appear side by side.

<ParamField body="pageId" type="string" required>
  The page the group belongs to.
</ParamField>

<ParamField body="groupId" type="string" required>
  The group to add blocks to.
</ParamField>

<ParamField body="columns" type="array" required>
  Array of column objects. Each column contains a `blocks` array stacked vertically.
  Multiple columns appear side by side on the page.

  <Expandable title="Column object fields">
    <ParamField body="blocks" type="array" required>
      Array of block objects for this column.

      <Expandable title="Block object fields">
        <ParamField body="type" type="&#x22;text&#x22; | &#x22;image&#x22; | &#x22;embed&#x22; | &#x22;link&#x22; | &#x22;pdf&#x22; | &#x22;action-plan&#x22;" required>
          Block type. Immutable after creation.
        </ParamField>

        <ParamField body="content" type="string">
          Text content for `text` blocks. Accepts **Markdown** — bold, italic, headings,
          lists, tables, blockquotes, and code blocks are converted automatically.
        </ParamField>

        <ParamField body="url" type="string">
          URL for `image`, `embed`, `link`, and `pdf` blocks.
          For `image` and `pdf`, any public URL is accepted — the file is automatically
          fetched and stored in Flowla S3.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

### Layout examples

<AccordionGroup>
  <Accordion title="Single column (vertical stack)">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        {
          "blocks": [
            { "type": "text", "content": "## Welcome\n\nThis is **bold** text." },
            { "type": "image", "url": "https://cdn.example.com/banner.png" }
          ]
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Two side-by-side columns">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "text", "content": "Left column" }] },
        { "blocks": [{ "type": "image", "url": "https://cdn.example.com/img.png" }] }
      ]
    }
    ```
  </Accordion>

  <Accordion title="text">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "text", "content": "Welcome to the room." }] }
      ]
    }
    ```

    The `content` field accepts Markdown. Formatting like `**bold**`, `# Heading`, bullet lists, and tables are rendered correctly.
  </Accordion>

  <Accordion title="image">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "image", "url": "https://cdn.example.com/banner.png" }] }
      ]
    }
    ```

    The image is automatically fetched from the provided URL and stored in Flowla S3.
  </Accordion>

  <Accordion title="embed">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "embed", "url": "https://example.com/page" }] }
      ]
    }
    ```
  </Accordion>

  <Accordion title="link">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "link", "url": "https://example.com/pricing" }] }
      ]
    }
    ```
  </Accordion>

  <Accordion title="pdf">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "pdf", "url": "https://cdn.example.com/proposal.pdf" }] }
      ]
    }
    ```

    The PDF is automatically fetched and stored in Flowla S3.
  </Accordion>

  <Accordion title="action-plan">
    ```json theme={null}
    {
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [
        { "blocks": [{ "type": "action-plan" }] }
      ]
    }
    ```

    Once created, use the [Action Items](/api/action-items) endpoints to add tasks to this block.
  </Accordion>
</AccordionGroup>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.flowla.com/api/v2/blocks \
    -H "x-flowla-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "pageId": "<page_id>",
      "groupId": "<group_id>",
      "columns": [{ "blocks": [{ "type": "action-plan" }] }]
    }'
  ```

  ```python Python theme={null}
  import requests

  requests.post(
      "https://api.flowla.com/api/v2/blocks",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      json={
          "pageId": "<page_id>",
          "groupId": "<group_id>",
          "columns": [{"blocks": [{"type": "action-plan"}]}],
      },
  )
  ```

  ```js JavaScript theme={null}
  await fetch("https://api.flowla.com/api/v2/blocks", {
    method: "POST",
    headers: {
      "x-flowla-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pageId: "<page_id>",
      groupId: "<group_id>",
      columns: [{ blocks: [{ type: "action-plan" }] }],
    }),
  });
  ```
</CodeGroup>

***

## List blocks

`GET /api/v2/blocks?pageId={page_id}&groupId={group_id}`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.flowla.com/api/v2/blocks?pageId=<page_id>&groupId=<group_id>" \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.flowla.com/api/v2/blocks",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      params={"pageId": "<page_id>", "groupId": "<group_id>"},
  )
  ```
</CodeGroup>

***

## Update a block

`PATCH /api/v2/blocks/{block_id}`

<ParamField body="pageId" type="string" required>
  The page the block belongs to.
</ParamField>

<ParamField body="content" type="string">
  Updated text content (for `text` blocks). Accepts Markdown.
</ParamField>

<ParamField body="url" type="string">
  Updated URL (for `image`, `embed`, `link`, `pdf` blocks).
  For `image` and `pdf`, the file is automatically fetched and stored in Flowla S3.
</ParamField>

```json Example theme={null}
{ "pageId": "<page_id>", "content": "Updated **text** content" }
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.flowla.com/api/v2/blocks/<block_id> \
    -H "x-flowla-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"pageId": "<page_id>", "content": "Updated text content"}'
  ```

  ```python Python theme={null}
  requests.patch(
      "https://api.flowla.com/api/v2/blocks/<block_id>",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      json={"pageId": "<page_id>", "content": "Updated text content"},
  )
  ```
</CodeGroup>

***

## Delete a block

`DELETE /api/v2/blocks/{block_id}?pageId={page_id}`

<Warning>
  If the block is an `action-plan` block, all its action items are deleted too.
</Warning>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.flowla.com/api/v2/blocks/<block_id>?pageId=<page_id>" \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  requests.delete(
      "https://api.flowla.com/api/v2/blocks/<block_id>",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      params={"pageId": "<page_id>"},
  )
  ```
</CodeGroup>