---
title: "Create a checklist"
method: POST
path: "/checklists"
tags: ["Checklists"]
---

# Create a checklist

`POST /checklists`

## Request

- Base URL: `https://api.produktly.com/api/v1`
- URL: `https://api.produktly.com/api/v1/checklists`
- Auth: HTTP bearer

Creates the checklist as a draft. Pass active: true to publish immediately — the checklist must have at least one item and targeting set, otherwise it stays a draft and the response note explains why. The response includes a dashboardUrl for reviewing the checklist in the builder.

## Request body

- object
  - `name` string, required: Shown as the checklist panel header
  - `items` object[]
    - `id` string: Server-generated UUID — omit on create, preserve on update (completion state keys on it)
    - `title` string, required: Supports {{user.attr}} templates
    - `content` string: HTML body shown under the title (sanitized at render)
    - `type` 'start-tour' | 'open-url' | 'custom', required: Click action: start a tour, open a URL, or "custom" (no click action; completes via events)
    - `tourId` integer: Required when type=start-tour
    - `redirectToUrl` string: Required when type=open-url. Supports {user.attr} and {currentUrl} templates
    - `completionType` 'page-event' | 'manual-click' | 'tour-complete', required: What marks the item complete. page-event: a DOM event on the customer site; manual-click: the user ticks it; tour-complete: a tour finishes
    - `eventType` 'click' | 'hover' | 'element-visible': With completionType=page-event. Default "click". element-visible = present in DOM (checked every 2s)
    - `pageEventElementSelector` string: Required when completionType=page-event: CSS selector the event must hit
    - `tourToCompleteId` integer: Required when completionType=tour-complete (auto-filled from tourId for start-tour items)
    - `allowManualCompletion` union: Also allow ticking manually on top of page-event/tour-complete. Default no
      - boolean
      - 'yes' | 'no'
    - `allowToRetake` union: Completed items can still fire their click action. Default no
      - boolean
      - 'yes' | 'no'
    - `allowUncheck` union: Completed items can be unchecked. Default no
      - boolean
      - 'yes' | 'no'
  - `targeting` union
    - object
      - `showOnAllPages` true, required
    - object
      - `rules` object[], required
        - `type` union, required
          - 'url' | 'current_time' | 'time_of_day' | 'day_of_week' | 'location' | 'language' | 'produktly_user_created_at' | 'device_type' | 'screen_width' | 'screen_height' | 'produktly_user_visit_count' | 'produktly_user_days_active'
          - string
          - string
        - `comparisonOperator` 'equals' | 'not_equal' | 'contains' | 'no_contains' | 'starts_with' | 'ends_with' | 'one_of' | 'not_one_of' | 'greater' | 'greater_eq' | 'less' | 'less_eq' | 'exists' | 'not_exists' | 'time_ago' | 'within_last' | 'between', required
        - `value` union
          - string
          - number
          - union[]
            - union
              - …
          - object
            - `value` integer, required
            - `unit` 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years', required
      - `logicalOperator` 'AND' | 'OR' | 'and' | 'or': How multiple rules combine. Default "AND".
    - object
      - `userSegmentIds` integer[], required
  - `settings` object
    - `displayMode` 'floating' | 'embedded': Default "floating"
    - `containerSelector` string: Required when displayMode=embedded: CSS selector of the element to render into
    - `checklistStart` 'minified' | 'immediate' | 'manually': Default "minified". "manually" = only via Produktly.startChecklist()
    - `hideBeacon` union
      - boolean
      - 'yes' | 'no'
    - `checklistPosition` 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    - `beaconPosition` 'bottom-right' | 'bottom-left'
    - `themeColor` string
    - `textColor` string
    - `completedColor` string: Default "#61d345"
    - `showChecklistBtnText` string
    - `continueChecklistBtnText` string
    - `showChecklistAfterFinishBtnText` string
    - `percentageCompletedText` string
    - `checklistCompletedText` string
    - `finishChecklistBtnText` string
    - `markAsCompletedText` string
    - `markAsCompletedConfirmText` string
    - `markAsCompletedCancelText` string
    - `markAsUncompletedText` string
    - `markAsUncompletedConfirmText` string
    - `markAsUncompletedCancelText` string
  - `themeId` integer
  - `folderId` integer
  - `active` boolean: Publish immediately. The checklist needs at least one item and targeting set; otherwise it is saved as a draft and the response note explains why.

## Response `201`

Created checklist

- Checklist
  - `id` integer, required
  - `name` string, required
  - `active` boolean, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required
  - `folderId` integer, nullable, required
  - `themeId` integer, nullable, required
  - `items` object[], required
  - `settings` object, required
  - `rules` object[], required
  - `ruleLogicalOperator` string, nullable, required
  - `dashboardUrl` string, required
  - `note` string

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Plan limit reached
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/produktly/apis/produktly-api.md) · [All operations](https://skmtc.dev/produktly/apis/produktly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/produktly/apis/produktly-api/revisions/fd942a97a7d1?raw)