> ## 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 inside an action-plan block. Action items support assignees, dates, statuses, and internal visibility.

<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?pageId={page_id}&blockId={block_id}` | List action items in a block |
| `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        |

<Note>
  Both `pageId` and `blockId` are mandatory for listing and creating. The `blockId` must point to an existing `action-plan` block. See [Blocks](/api/blocks) to create one.
</Note>

## Action item fields

| Field         | Type      | Notes                                                                     |
| ------------- | --------- | ------------------------------------------------------------------------- |
| `title`       | string    | **Required.**                                                             |
| `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`   | string\[] | Emails. Org members linked internally; others added as external contacts. |

***

## List action items

`GET /api/v2/action-items?pageId={page_id}&blockId={block_id}`

<CodeGroup>
  ```bash cURL 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={"pageId": "<page_id>", "blockId": "<block_id>"},
  )
  ```

  ```js JavaScript theme={null}
  const res = await fetch(
    "https://api.flowla.com/api/v2/action-items?pageId=<page_id>&blockId=<block_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",
          "assignees": ["buyer@example.com"]
        },
        { "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",
                  "status": "in_progress",
                  "dueDate": "2026-06-01",
                  "assignees": ["buyer@example.com"],
              },
              {"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",
          status: "in_progress",
          dueDate: "2026-06-01",
          assignees: ["buyer@example.com"],
        },
        { 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 the action item is hidden from buyers.
</ParamField>

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