Create Docs with the ClickUp API

Using the ClickUp public API, you can programmatically create Docs inside a Workspace, List, or Folder. This how-to guide walks you through every required field, parameter, and option so you can confidently build and automate document workflows with ClickUp.

Understanding the ClickUp create Doc endpoint

The createDocPublic endpoint lets you create a Doc in a specific location using an HTTP POST request. You send JSON data to define the Doc’s name, content, sharing options, and where it should live within ClickUp.

The endpoint is:

POST https://api.clickup.com/api/v2/doc

You must include an API token in the request headers and a valid location in the request body. The Doc can be attached to a Workspace, List, or Folder depending on your use case.

Prerequisites for using the ClickUp API

Before calling the API, set up a few essentials in ClickUp and your development environment.

• A ClickUp Workspace where Docs and tasks will live.
• An API token generated from your ClickUp account.
• HTTP client tooling such as cURL, Postman, or a custom script.
• The target location ID (Workspace, List, or Folder) where the Doc will be created.

Always keep your API token secure. Do not hard-code it in client-side code or share it publicly.

Required headers for ClickUp Doc creation

Every request must include specific headers so ClickUp can authenticate and interpret your data correctly.

• Authorization: Your personal API token.
• Content-Type: Must be application/json.

Example headers:

Authorization: <YOUR_API_TOKEN>
Content-Type: application/json

Core request body fields in ClickUp

The JSON body defines what the Doc looks like and where it lives in ClickUp. Below are the core fields.

• name (string): The Doc name. Required.
• content (string): The initial Doc content. Optional but recommended.
• location_id (string): The ID of the Workspace, List, or Folder. Required.
• location_type (string): The type of location. Required. Accepts values like workspace, list, or folder depending on the API specification.
• sharing_override (boolean): Whether to override default sharing.
• public (object): Configuration for public sharing if enabled.

At minimum, you must send name, location_id, and location_type for the Doc to be created in ClickUp.

Step-by-step: create a Doc in ClickUp

1. 1. Locate your ClickUp Workspace or List ID

   Identify the ID for the Workspace, List, or Folder where you want the Doc to be created. You can obtain IDs using other endpoints in the ClickUp API, such as listing Workspaces, Spaces, Folders, or Lists.

2. 2. Prepare the JSON payload for ClickUp

   Create a JSON object describing the Doc. A basic payload might look like this:

   {
     "name": "Project Overview",
     "content": "# Project Overview\nInitial scope and objectives.",
     "location_id": "1234",
     "location_type": "list"
   }

   This example adds a Doc named “Project Overview” to a List in ClickUp with ID 1234.

3. 3. Send the POST request to ClickUp

   Use your preferred HTTP client to send the request with headers and JSON body. An example with cURL:

   curl -X POST "https://api.clickup.com/api/v2/doc" \
     -H "Authorization: <YOUR_API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Project Overview",
       "content": "# Project Overview\nInitial scope and objectives.",
       "location_id": "1234",
       "location_type": "list"
     }'

   If the request is valid, ClickUp responds with a JSON object describing the newly created Doc, including its ID, URL, and metadata.

4. 4. Store the ClickUp Doc ID from the response

   Parse the API response and capture the Doc ID and URL. These values let you:

   • Link back to the Doc from your app.
   • Update the Doc content later.
   • Manage sharing and permissions using other ClickUp API endpoints.

Managing public sharing options in ClickUp

The create Doc endpoint can also configure public sharing if the feature is available in your ClickUp plan and Workspace settings.

Within the request body, the public object can include settings such as:

• Enabling or disabling public access.
• Allowing comments or edits for public viewers, if supported.
• Defining password or security rules when applicable.

If you enable public sharing via the API, confirm that your Workspace-level sharing controls in ClickUp allow public Docs.

Error handling with the ClickUp API

When you send an invalid request, the API returns an error response with an HTTP status code and message. Typical issues include:

• Missing or invalid Authorization header.
• Missing required fields such as name, location_id, or location_type.
• Using a location ID that does not exist or that you do not have permission to access in ClickUp.

Add robust error handling in your integration to log these responses and provide useful feedback to end users or monitoring tools.

Best practices for ClickUp Doc automation

To build reliable document workflows with ClickUp, keep these best practices in mind:

• Use environment variables to store API tokens securely.
• Validate input such as Doc names and content before sending requests.
• Implement retries with backoff for transient network errors.
• Log request IDs and Doc IDs for troubleshooting across ClickUp and your own systems.
• Test in a separate Workspace before deploying new automation at scale.

Where to find more ClickUp API details

For full parameter documentation, error schemas, and advanced examples, refer to the official endpoint reference:

ClickUp createDocPublic API reference

If you want expert help designing end-to-end workflows or optimizing how you use ClickUp in your organization, you can learn more at Consultevo.

Summary: automate Docs with the ClickUp API

The create Doc endpoint lets you generate rich documentation directly from your apps and scripts. By setting the correct headers, providing a valid location, and handling responses properly, you can integrate Docs into your existing processes, automate project documentation, and maintain a consistent source of truth inside ClickUp.