**Version: 202601**

# Add block to a card

**POST** `/openapi/2026-01/themes/edit-sessions/:oseid/sections/:section_id/blocks`

Append/insert a block into a card within an edit session.

## Request

**Path Parameters**

- `oseid` string (required)

  Edit session ID
- `section_id` string (required)

  Section instance ID inside the document; a global card id (`header`, `footer`, `announcement`, `cart_drawer`) also works

**application/json**

**Body | Example**

**Body (required)**

- `doc_id` string (required)

  Document (template file) ID
- `theme_id` string (required)

  Theme ID (for rendering context url)
- `block` object (required)

  The block object to add, e.g. `{type, settings}`
- `index` int32

  0-based insert position within the parent's blocks (the section root when `parent_path` is empty). Pass -1 (or any value past the end) to append. Omitted = 0 = insert at the front
- `parent_path` int32[]

  Ancestor index path from the section root to the parent block the new block is inserted into (each element a 0-based index into a blocks array); empty = insert at top-level. e.g. `parent_path=[1,0]` with `index=-1` appends into `section.blocks[1].blocks[0].blocks`
- `template_name` string

  Template name; defaults to file location without `.liquid`
- `locale` string

  Rendering locale; defaults to en\_US

```json
{
  "doc_id": "string",
  "theme_id": "string",
  "block": {},
  "index": 0,
  "parent_path": [
    0
  ],
  "template_name": "string",
  "locale": "string"
}
```

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `section` object

    The updated section object
  - `html` string

    Rendered section HTML. Empty when the target is a global card (header / footer / ...) — those are not re-rendered per section

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "section": {},
    "html": "string"
  }
}
```