> ## 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.

# Action Items

> Create and manage action items (Mutual Action Plan tasks). Supports room-wide, page-wide, and block-scoped listing with pagination.

<Note>
  **Terminology:** the *action-plan block* is the container (created via
  `POST /api/v2/blocks` with `type: "action-plan"`). The individual tasks
  inside it are called **action items** and are managed via the endpoints
  on this page.
</Note>

## Endpoints

| Method | Path | Description |
| - | - | - |
| `GET` | `/api/v2/action-items` | List action items |
| `POST` | `/api/v2/action-items` | Create action items |
| `PATCH` | `/api/v2/action-items/{action_item_id}` | Update an action item |
| `DELETE` | `/api/v2/action-items/{action_item_id}` | Delete an action item |

## Action item fields

| Field | Type | Notes |
| - | - | - |
| `id` | string | |
| `blockId` | string \| null | ID of the action-plan block this item belongs to |
| `title` | string | **Required on create.** |
| `description` | string | |
| `status` | enum | `todo`, `in_progress`, `done`, `cancelled` |
| `startDate` | string | ISO 8601 |
| `dueDate` | string | ISO 8601 |
| `internal` | boolean | Hidden from buyers when `true`. Default `false`. |
| `assignees` | object\[] | `{ userId, email, name }` per assignee |
| `completedAt` | string \| null | ISO 8601 |
| `createdAt` | string | ISO 8601 |
| `updatedAt` | string | ISO 8601 |

***

## List action items

`GET /api/v2/action-items`

Returns action items scoped to a room, page, or specific block.
All scope parameters are optional, but at least one should be
provided. If `blockId` is set, `pageId` **must** also be set
(otherwise the API returns 400).

### Scoping

| `roomId` | `pageId` | `blockId` | Result |
| - | - | - | - |
| ✓ | — | — | All action items in the room |
| — | ✓ | — | All action items on the page |
| — | ✓ | ✓ | Action items in the specific block |
| — | — | ✓ | **400 Bad Request** |

### Query parameters

<ParamField query="roomId" type="string">
  Room ID — returns all action items across the room.
</ParamField>

<ParamField query="pageId" type="string">
  Page ID — returns all action items on the page.
</ParamField>

<ParamField query="blockId" type="string">
  Action-plan block ID — returns items in that block.
  Requires `pageId`.
</ParamField>

<ParamField query="page" type="number">
  Page number (default: 1).
</ParamField>

<ParamField query="limit" type="number">
  Results per page (default: 100, max: 1000).
</ParamField>

### Response

```json theme={null}
{
  "items": [ ... ],
  "totalRecords": 42,
  "totalPages": 1
}
```

<CodeGroup>
  ```bash cURL — room scope theme={null}
  curl "https://api.flowla.com/api/v2/action-items?roomId=<room_id>" \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```bash cURL — page scope theme={null}
  curl "https://api.flowla.com/api/v2/action-items?pageId=<page_id>" \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```bash cURL — block scope theme={null}
  curl "https://api.flowla.com/api/v2/action-items?pageId=<page_id>&blockId=<block_id>" \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

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

  response = requests.get(
      "https://api.flowla.com/api/v2/action-items",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      params={"roomId": "<room_id>"},
  )
  ```

  ```js JavaScript theme={null}
  const res = await fetch(
    "https://api.flowla.com/api/v2/action-items?roomId=<room_id>",
    { headers: { "x-flowla-api-key": "YOUR_API_KEY" } }
  );
  ```
</CodeGroup>

***

## Create action items

`POST /api/v2/action-items`

<ParamField body="pageId" type="string" required>
  The page containing the action-plan block.
</ParamField>

<ParamField body="blockId" type="string" required>
  The action-plan block to add action items to.
</ParamField>

<ParamField body="items" type="array" required>
  Array of action item objects.
</ParamField>

```json Example theme={null}
{
  "pageId": "<page_id>",
  "blockId": "<block_id>",
  "items": [
    {
      "title": "Review proposal",
      "description": "Check pricing and terms",
      "status": "in_progress",
      "startDate": "2026-05-28",
      "dueDate": "2026-06-01",
      "internal": false,
      "assignees": ["owner@example.com", "buyer@example.com"]
    },
    { "title": "Schedule kickoff call", "status": "todo" }
  ]
}
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.flowla.com/api/v2/action-items \
    -H "x-flowla-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "pageId": "<page_id>",
      "blockId": "<block_id>",
      "items": [
        { "title": "Review proposal", "status": "in_progress", "dueDate": "2026-06-01" },
        { "title": "Confirm legal sign-off", "internal": true }
      ]
    }'
  ```

  ```python Python theme={null}
  requests.post(
      "https://api.flowla.com/api/v2/action-items",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      json={
          "pageId": "<page_id>",
          "blockId": "<block_id>",
          "items": [
              {"title": "Review proposal", "dueDate": "2026-06-01"},
              {"title": "Confirm legal sign-off", "internal": True},
          ],
      },
  )
  ```

  ```js JavaScript theme={null}
  await fetch("https://api.flowla.com/api/v2/action-items", {
    method: "POST",
    headers: {
      "x-flowla-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      pageId: "<page_id>",
      blockId: "<block_id>",
      items: [
        { title: "Review proposal", dueDate: "2026-06-01" },
        { title: "Confirm legal sign-off", internal: true },
      ],
    }),
  });
  ```
</CodeGroup>

***

## Update an action item

`PATCH /api/v2/action-items/{action_item_id}`

All fields are optional. `assignees` **replaces** the full assignee list.

<ParamField body="title" type="string">Updated title.</ParamField>
<ParamField body="description" type="string">Updated description.</ParamField>
<ParamField body="status" type="&#x22;todo&#x22; | &#x22;in_progress&#x22; | &#x22;done&#x22; | &#x22;cancelled&#x22;">New status.</ParamField>
<ParamField body="startDate" type="string">ISO 8601 start date.</ParamField>
<ParamField body="dueDate" type="string">ISO 8601 due date.</ParamField>
<ParamField body="internal" type="boolean">Whether hidden from buyers.</ParamField>

<ParamField body="assignees" type="string[]">
  Replaces the full assignee list. Pass an empty array to remove all.
</ParamField>

```json Example theme={null}
{ "status": "done", "assignees": ["alex@ourcompany.com"] }
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH https://api.flowla.com/api/v2/action-items/<action_item_id> \
    -H "x-flowla-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"status": "done"}'
  ```

  ```python Python theme={null}
  requests.patch(
      "https://api.flowla.com/api/v2/action-items/<action_item_id>",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
      json={"status": "done"},
  )
  ```

  ```js JavaScript theme={null}
  await fetch("https://api.flowla.com/api/v2/action-items/<action_item_id>", {
    method: "PATCH",
    headers: { "x-flowla-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ status: "done" }),
  });
  ```
</CodeGroup>

***

## Delete an action item

`DELETE /api/v2/action-items/{action_item_id}`

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.flowla.com/api/v2/action-items/<action_item_id> \
    -H "x-flowla-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  requests.delete(
      "https://api.flowla.com/api/v2/action-items/<action_item_id>",
      headers={"x-flowla-api-key": "YOUR_API_KEY"},
  )
  ```

  ```js JavaScript theme={null}
  await fetch("https://api.flowla.com/api/v2/action-items/<action_item_id>", {
    method: "DELETE",
    headers: { "x-flowla-api-key": "YOUR_API_KEY" },
  });
  ```
</CodeGroup>


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