×

Create Lists in ClickUp via API

/ ClickUp / By

Create a Folderless List in ClickUp via API

This guide explains how to create a folderless list in ClickUp using the REST API. You will learn the required endpoint, headers, body parameters, and how to send requests with JSON payloads in your preferred HTTP client or integration.

The instructions below are based directly on the official API reference so you can implement a reliable and predictable workflow integration.

Overview of the ClickUp folderless list endpoint

The ClickUp API exposes a specific endpoint to create a folderless list inside a given space. Instead of placing a list into a folder, this operation associates it directly with a space, which is useful when you prefer a flatter hierarchy or when your workspace does not use folders.

The main characteristics of this endpoint are:

  • HTTP method: POST
  • Authentication: Personal API token in the Authorization header
  • Request body: JSON object describing the list properties
  • Response: JSON object with the newly created list, including IDs and metadata

All behavior, limits, and field definitions are controlled by the public API contract documented on the official reference page.

ClickUp API endpoint and path format

To create a folderless list, send a POST request to the space-specific endpoint. The URL pattern is:

POST https://api.clickup.com/api/v2/space/{space_id}/list

Replace {space_id} with the numeric ID of your target space. This ID can be obtained from other API endpoints that list spaces in your workspace.

Required headers for ClickUp requests

Your HTTP request must include the correct headers. At minimum, you need:

  • Authorization: your ClickUp API token as a string.
  • Content-Type: application/json for JSON requests.

Ensure that the authorization token has sufficient permissions to create lists within the selected space.

Request body fields for a ClickUp folderless list

The request body is a JSON object. Some properties are required, while others are optional and let you customize scheduling and visibility. The exact fields are defined in the API reference at the official ClickUp documentation.

Core fields

These fields typically control the main behavior of the new list:

  • name (string): The title that will appear for the list in the workspace UI.
  • content (string, optional): A description or notes for the list.
  • due_date (integer, optional): A timestamp in milliseconds for the list due date.
  • due_date_time (boolean, optional): Indicates whether the due date includes a time value.
  • priority (integer, optional): A numeric priority value, when supported by the workspace configuration.
  • assignee (integer, optional): User ID to assign the list, where applicable.
  • status (string, optional): List status key depending on the space configuration.

Consult the reference page for the most accurate list of supported fields and their data types, as these can evolve over time.

Date and time behavior in ClickUp lists

When using date fields for a new list, remember:

  • Timestamps are usually expressed in Unix epoch milliseconds.
  • If you set due_date_time to true, the API treats the due_date as a precise date-time instead of a date-only value.
  • Time zone handling is governed by system defaults and workspace settings, so verify the results by reading the list back after creation.

Step-by-step: create a folderless list with the ClickUp API

Follow these steps to perform the operation reliably in any HTTP client, scripting language, or automation platform.

1. Get your ClickUp API token

Before sending any request, obtain a personal API token from your account. Store it securely and never hard-code it into client-side apps or public repositories.

  1. Sign in to your workspace.
  2. Open your user settings.
  3. Locate the API token section.
  4. Generate or copy your token for use in the Authorization header.

2. Identify the target space ID

You must know the ID of the space where the new folderless list will live.

  1. Use the API endpoint that lists spaces for your team, or
  2. Use administrative tools that display internal IDs.

Once you have the space identifier, substitute it into the endpoint path.

3. Build the POST request for ClickUp

Construct the HTTP POST request as follows:

  • URL: https://api.clickup.com/api/v2/space/{space_id}/list
  • Method: POST
  • Headers:
    • Authorization: <your_token>
    • Content-Type: application/json
  • Body (JSON example):
{
  "name": "Product Roadmap",
  "content": "Top-level roadmap list for the product team.",
  "due_date": 1735689600000,
  "due_date_time": true,
  "priority": 3
}

Adjust these values to match your use case, adding or removing optional fields according to the API reference.

4. Send the request and verify the ClickUp response

After sending the POST request:

  1. Expect an HTTP success status code (for example, 200 or 201, depending on the API configuration).
  2. Parse the response body JSON to retrieve the new list ID and related metadata.
  3. Store the list ID safely if you plan to create tasks, update the list, or reference it in automations.

If you receive an error status code, check authentication, space permissions, required fields, and the exact error message returned by the API.

Handling errors and constraints in the ClickUp API

When creating a list, the API might reject invalid or incomplete requests. Common issues include:

  • Missing or invalid Authorization header.
  • Incorrect space ID or insufficient permissions.
  • Omission of required fields such as name.
  • Invalid data types, such as sending a string where an integer timestamp is required.

Always log the full response body when debugging. The server usually returns structured error details that indicate what went wrong, helping you correct your payload quickly.

Best practices for using the ClickUp list endpoint

To keep your integration reliable and maintainable, apply the following practices:

  • Validate payloads before sending them to the API.
  • Use environment variables or secure vaults for API tokens.
  • Implement retry logic for transient network errors.
  • Respect rate limits documented by the service.
  • Maintain version awareness by checking the current API documentation regularly.

For broader workflow and integration strategy, you can also consult expert implementation resources such as Consultevo, which covers automation and platform integration patterns.

Where to find authoritative ClickUp API details

Because APIs evolve, always confirm field names, types, and behaviors with the official documentation. The complete, authoritative reference for this operation is published at Create Folderless List in ClickUp. That page includes up-to-date schemas, sample requests, and any new options that might be added after this guide.

By following the steps and guidelines in this article, you can confidently create folderless lists through the ClickUp REST API and integrate them into your existing automation, reporting, or project management workflows.

Need Help With ClickUp?

If you want expert help building, automating, or scaling your ClickUp workspace, work with ConsultEvo — trusted ClickUp Solution Partners.

Get Help

“`

Verified by MonsterInsights