ClickUp API Client

A TypeScript-based client for interacting with the ClickUp API. This library provides an easy-to-use, type-safe interface for managing Workspaces (teams), Spaces, Folders, Lists, and Tasks in ClickUp.

Features

• Fetch Workspaces (teams), Spaces, Folders, Lists, and Tasks from ClickUp
• Retrieve detailed information about specific entities
• Supports TypeScript for strong typing and autocompletion
• Modular design with separate classes for each resource type
• Built with axios for reliable HTTP requests

Installation

Install the package via npm:

npm install @hot-gmbh/clickup

Usage

This package implements the functionality documented in the ClickUp API documentation and mirrors the routes available in their Postman collection.

Basic Example

import { ClickUp } from "@hot-gmbh/clickup";

const apiKey = process.env.CLICKUP_API_KEY; // Replace with your ClickUp API key

const clickUp = new ClickUp(apiKey);

// Fetch all spaces for a team
const spaces = await clickUp.spaces.getAll("your_team_id");
console.log("Spaces:", spaces);
console.log("First space ID:", spaces[0].id);

Advanced Example

import { ClickUp } from "@hot-gmbh/clickup";

async function main() {
  const clickUp = new ClickUp(process.env.CLICKUP_API_KEY);

  // Get all teams (workspaces)
  const teams = await clickUp.teams.getAll();
  const teamId = teams[0].id;

  // Get spaces for a team, including archived ones
  const spaces = await clickUp.spaces.getAll(teamId, true);
  console.log("Spaces:", spaces);

  // Get folders for a space
  const spaceId = spaces[0].id;
  const folders = await clickUp.folders.getAll(spaceId);
  console.log("Folders:", folders);

  // Get lists for a folder
  const folderId = folders[0]?.id;
  if (folderId) {
    const lists = await clickUp.lists.getAll(folderId);
    console.log("Lists:", lists);
  }

  // Get folderless lists for a space
  const folderlessLists = await clickUp.lists.getFolderless(spaceId);
  console.log("Folderless Lists:", folderlessLists);
}

main().catch(console.error);

API Documentation

Initialization

const clickUp = new ClickUp(apiKey: string, baseUrl?: string);

• apiKey: Your ClickUp personal API token (e.g., pk__xxxx_...)
• baseUrl: Optional base URL for the ClickUp API (defaults to https://api.clickup.com/api/v2)

Methods

Teams (Workspaces)

Accessed via clickUp.teams

• getAll(): Promise<Team[]>

  • Fetches all teams (workspaces) accessible with the API key
  • Returns an array of Team objects

Spaces

Accessed via clickUp.spaces

• getAll(teamId: string | number, includeArchived?: boolean): Promise<Space[]>
  • Fetches all spaces for a given team.
  • teamId: The ID of the team/workspace.
  • includeArchived: Optional, includes archived spaces if true (default: false).
  • Returns an array of Space objects.

Folders

Accessed via clickUp.folders

• getAll(spaceId: string | number): Promise<Folder[]>
  • Fetches all folders within a space.
  • spaceId: The ID of the space.
  • Returns an array of Folder objects or an empty array if none exist.

Lists

Accessed via clickUp.lists

• getAll(folderId: string | number): Promise<List[]> - Fetches all lists within a folder. - folderId: The ID of the folder. - Returns an array of List objects.

• getFolderless(spaceId: string | number): Promise<List[]>

  • Fetches all lists directly under a space (not in a folder).
  • spaceId: The ID of the space.
  • Returns an array of List objects.

Development

Setup

• Clone the repository:

git clone https://github.com/hot-gmbh/clickup.git
cd clickup

• Install dependencies:

npm install

• Build the project:

npm run build

Project Structure

clickup/
├── src/
│ ├── clickup.ts # Main ClickUp class
│ ├── teams.ts # Teams (Workspaces) operations
│ ├── spaces.ts # Spaces operations
│ ├── folders.ts # Folders operations
│ ├── lists.ts # Lists operations
│ ├── types.ts # Shared TypeScript types
│ └── index.ts # Entry point exporting ClickUp
├── dist/ # Compiled JavaScript output
├── package.json
└── tsconfig.json

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit your changes (git commit -m "Add your feature").
4. Push to the branch (git push origin feature/your-feature).
5. Open a Pull Request.

Guidelines

• Follow TypeScript best practices
• Add tests for new features (if a test suite is added)
• Update the README with new methods or changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Issues

If you encounter bugs or have feature requests, please open an issue on GitHub.

Acknowledgments

• Built with axios for HTTP requests.
• Inspired by the ClickUp API documentation.