How to List Public Docs with the ClickUp API

The ClickUp developer platform lets you retrieve public Docs via a dedicated REST endpoint. This guide explains how to call the GET /public/v1/team/{team_id}/doc endpoint to list public Doc Pages, including required parameters, authentication, request examples, and how to interpret the response.

Overview of the ClickUp public Docs endpoint

The public Docs endpoint gives you read-only access to all publicly shared Docs that belong to a specific Workspace (team). You can use it to build integrations, dashboards, or custom documentation experiences outside the main app.

The core endpoint is:

GET https://api.clickup.com/public/v1/team/{team_id}/doc

This endpoint returns an array of public Doc Pages for the team you specify. All results are scoped to Docs that have been shared publicly from that Workspace.

Prerequisites for using the ClickUp Docs API

Before calling the public Docs endpoint, make sure you have the following in place:

• A ClickUp Workspace (team) with at least one Doc shared publicly.
• The team_id for that Workspace.
• A valid public API token that grants access to public Docs.
• Basic familiarity with making HTTP requests using tools like curl, Postman, or a server-side language.

If you need help planning a broader integration strategy, you can find consulting and implementation support from specialized ClickUp solution partners.

Understanding the ClickUp endpoint structure

The public Docs listing endpoint follows a consistent structure:

• Base URL: https://api.clickup.com
• Version: /public/v1
• Resource: /team/{team_id}/doc

Combining these parts gives you the full URL for the request. Replace {team_id} with your actual numeric team identifier.

Required path parameter: team_id in ClickUp

The team_id is a required path parameter that identifies which Workspace you want to query. The endpoint will only return public Docs that belong to this team.

Example with a sample team ID:

GET https://api.clickup.com/public/v1/team/123456/doc

If the team has no public Docs, the response will contain an empty list.

Authentication for ClickUp public Docs

All requests to the public Docs endpoint must be authenticated. The API expects an authorization token in the request headers.

Authorization header format in ClickUp requests

Send your token using the Authorization header:

Authorization: <your_public_api_token>

In most HTTP clients, you add this header as a key-value pair. The server uses this token to verify you have access to read public Docs for the specified team.

Make sure you keep the token secure and never expose it directly in client-side code or public repositories.

Optional query parameters supported by ClickUp

The public Docs endpoint supports additional query parameters you can pass to refine the results or change the response structure. Always refer to the official documentation for the latest list of parameters and behavior.

You can review all options directly in the reference here: ClickUp public Doc Pages API reference.

Typical behaviors you may find include:

• Filtering returned Docs.
• Limiting how many items are returned per request.
• Paginating through large collections of Docs.
• Controlling which fields appear in the response objects.

Use query parameters on the URL, for example:

GET https://api.clickup.com/public/v1/team/123456/doc?limit=50

Step-by-step: Calling the ClickUp public Docs endpoint

Follow these steps to successfully make your first request.

Step 1: Locate your ClickUp team_id

You can obtain your team ID from other API endpoints or from your Workspace settings. Once you have identified the correct ID, note it down for use in your requests.

Step 2: Prepare your authorization token in ClickUp

Generate or retrieve your public API token from your developer or integration settings. Ensure the token is active and has access to the relevant Workspace.

Store it securely in environment variables or a secrets manager. You will use it to construct the Authorization header.

Step 3: Build the request URL for ClickUp Docs

Insert your team ID into the path component of the endpoint:

https://api.clickup.com/public/v1/team/<team_id>/doc

Optionally, append query parameters for pagination or filtering if supported. For example:

https://api.clickup.com/public/v1/team/123456/doc?limit=25

Step 4: Add headers and send the ClickUp request

Use your preferred HTTP client and configure the request:

• Method: GET
• URL: full endpoint with your team ID
• Headers:
  • Authorization: <your_public_api_token>
  • Content-Type: application/json (often set automatically)

Example using curl:

curl -X GET 
  'https://api.clickup.com/public/v1/team/123456/doc' 
  -H 'Authorization: YOUR_PUBLIC_API_TOKEN'

Step 5: Review the ClickUp API response

If the request is successful, you will receive a JSON response containing a list of public Doc Pages. The top-level structure typically includes:

• A collection of Doc objects.
• Fields describing each Doc, such as identifiers, titles, and sharing status.
• Any pagination data if multiple pages of results are available.

Use this data to render lists of Docs in your application, build search interfaces, or synchronize documentation content with other systems.

Handling errors from the ClickUp Docs endpoint

When the endpoint cannot complete your request, it returns an HTTP error code alongside an error payload. Common causes include:

• Missing or invalid Authorization header.
• Incorrect team_id value.
• Network connectivity issues.
• Temporary service problems.

Check the status code and error message in the response to understand the root cause. Ensure your token is correct, the team ID is valid, and the Docs are actually shared publicly.

Best practices for integrating ClickUp public Docs

When integrating this endpoint into production systems, consider the following best practices:

• Cache responses for short periods to reduce the number of API calls and improve performance.
• Implement pagination if your Workspace maintains a large number of public Docs.
• Secure your token by keeping it on the server side and never exposing it in frontend code.
• Monitor rate limits and error rates to detect issues early.

By following these guidelines, you can create stable, scalable integrations around the public Docs features.

Next steps with the ClickUp Docs API

Once you can successfully list public Docs, you can expand your integration to include other endpoints, such as reading detailed content for a single Doc, or connecting Doc data to other tools and workflows.

To explore all available request parameters and the full response schema, review the official reference for the GET /public/v1/team/{team_id}/doc endpoint here: ClickUp public Doc Pages reference.

With this foundation, you can confidently build custom documentation portals, dashboards, and reporting solutions that leverage public Docs from your Workspace using the ClickUp API.

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

“`