ClickUp Install & Auth

Overview

Set up ClickUp SDK/CLI and configure authentication credentials.

Prerequisites

• Node.js 18+ or Python 3.10+
• Package manager (npm, pnpm, or pip)
• ClickUp account with API access
• API key from ClickUp dashboard

Instructions

Step 1: Install SDK

# Node.js
npm install @clickup/sdk

# Python
pip install clickup

Step 2: Configure Authentication

# Set environment variable
export CLICKUP_API_KEY="your-api-key"

# Or create .env file
echo 'CLICKUP_API_KEY=your-api-key' >> .env

Step 3: Verify Connection

// Test connection code here

Output

• Installed SDK package in node_modules or site-packages
• Environment variable or .env file with API key
• Successful connection verification output

Error Handling

Examples

TypeScript Setup

import { ClickUpClient } from '@clickup/sdk';

const client = new ClickUpClient({
  apiKey: process.env.CLICKUP_API_KEY,
});

Python Setup

from clickup import ClickUpClient

client = ClickUpClient(
    api_key=os.environ.get('CLICKUP_API_KEY')
)

Resources

• ClickUp Documentation
• ClickUp Dashboard
• ClickUp Status

Next Steps

After successful auth, proceed to clickup-hello-world for your first API call.

ClickUp Multi-Environment Setup

Overview

Configure ClickUp across development, staging, and production environments.

Prerequisites

• Separate ClickUp accounts or API keys per environment
• Secret management solution (Vault, AWS Secrets Manager, etc.)
• CI/CD pipeline with environment variables
• Environment detection in application

Environment Strategy

Configuration Structure

config/
├── clickup/
│   ├── base.json           # Shared config
│   ├── development.json    # Dev overrides
│   ├── staging.json        # Staging overrides
│   └── production.json     # Prod overrides

base.json

{
  "timeout": 30000,
  "retries": 3,
  "cache": {
    "enabled": true,
    "ttlSeconds": 60
  }
}

development.json

{
  "apiKey": "${CLICKUP_API_KEY}",
  "baseUrl": "https://api-sandbox.clickup.com",
  "debug": true,
  "cache": {
    "enabled": false
  }
}

staging.json

{
  "apiKey": "${CLICKUP_API_KEY_STAGING}",
  "baseUrl": "https://api-staging.clickup.com",
  "debug": false
}

production.json

{
  "apiKey": "${CLICKUP_API_KEY_PROD}",
  "baseUrl": "https://api.clickup.com",
  "debug": false,
  "retries": 5
}

Environment Detection

// src/clickup/config.ts
import baseConfig from '../../config/clickup/base.json';

type Environment = 'development' | 'staging' | 'production';

function detectEnvironment(): Environment {
  const env = process.env.NODE_ENV || 'development';
  const validEnvs: Environment[] = ['development', 'staging', 'production'];
  return validEnvs.includes(env as Environment)
    ? (env as Environment)
    : 'development';
}

export function getClickUpConfig() {
  const env = detectEnvironment();
  const envConfig = require(`../../config/clickup/${env}.json`);

  return {
    ...baseConfig,
    ...envConfig,
    environment: env,
  };
}

Secret Management by Environment

Local Development

# .env.local (git-ignored)
CLICKUP_API_KEY=sk_tes

ClickUp Observability

Overview

Set up comprehensive observability for ClickUp integrations.

Prerequisites

• Prometheus or compatible metrics backend
• OpenTelemetry SDK installed
• Grafana or similar dashboarding tool
• AlertManager configured

Metrics Collection

Key Metrics

Prometheus Metrics

import { Registry, Counter, Histogram, Gauge } from 'prom-client';

const registry = new Registry();

const requestCounter = new Counter({
  name: 'clickup_requests_total',
  help: 'Total ClickUp API requests',
  labelNames: ['method', 'status'],
  registers: [registry],
});

const requestDuration = new Histogram({
  name: 'clickup_request_duration_seconds',
  help: 'ClickUp request duration',
  labelNames: ['method'],
  buckets: [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5],
  registers: [registry],
});

const errorCounter = new Counter({
  name: 'clickup_errors_total',
  help: 'ClickUp errors by type',
  labelNames: ['error_type'],
  registers: [registry],
});

Instrumented Client

async function instrumentedRequest<T>(
  method: string,
  operation: () => Promise<T>
): Promise<T> {
  const timer = requestDuration.startTimer({ method });

  try {
    const result = await operation();
    requestCounter.inc({ method, status: 'success' });
    return result;
  } catch (error: any) {
    requestCounter.inc({ method, status: 'error' });
    errorCounter.inc({ error_type: error.code || 'unknown' });
    throw error;
  } finally {
    timer();
  }
}

Distributed Tracing

OpenTelemetry Setup

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('clickup-client');

async function tracedClickUpCall<T>(
  operationName: string,
  operation: () => Promise<T>
): Promise<T> {
  return tracer.startActiveSpan(`clickup.${operationName}`, async (span) => {
    try {
      const result = await operation();
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (error: any) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
     

ClickUp Performance Tuning

Overview

Optimize ClickUp API performance with caching, batching, and connection pooling.

Prerequisites

• ClickUp SDK installed
• Understanding of async patterns
• Redis or in-memory cache available (optional)
• Performance monitoring in place

Latency Benchmarks

Caching Strategy

Response Caching

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60000, // 1 minute
  updateAgeOnGet: true,
});

async function cachedClickUpRequest<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttl?: number
): Promise<T> {
  const cached = cache.get(key);
  if (cached) return cached as T;

  const result = await fetcher();
  cache.set(key, result, { ttl });
  return result;
}

Redis Caching (Distributed)

import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function cachedWithRedis<T>(
  key: string,
  fetcher: () => Promise<T>,
  ttlSeconds = 60
): Promise<T> {
  const cached = await redis.get(key);
  if (cached) return JSON.parse(cached);

  const result = await fetcher();
  await redis.setex(key, ttlSeconds, JSON.stringify(result));
  return result;
}

Request Batching

import DataLoader from 'dataloader';

const clickupLoader = new DataLoader<string, any>(
  async (ids) => {
    // Batch fetch from ClickUp
    const results = await clickupClient.batchGet(ids);
    return ids.map(id => results.find(r => r.id === id) || null);
  },
  {
    maxBatchSize: 100,
    batchScheduleFn: callback => setTimeout(callback, 10),
  }
);

// Usage - automatically batched
const [item1, item2, item3] = await Promise.all([
  clickupLoader.load('id-1'),
  clickupLoader.load('id-2'),
  clickupLoader.load('id-3'),
]);

Connection Optimization

import { Agent } from 'https';

// Keep-alive connection pooling
const agent = new Agent({
  keepAlive: true,
  maxSockets: 10,
  maxFreeSockets: 5,
  timeout: 30000,
});

const client = new ClickUpClient({
  apiKey: process.env.CLICKUP_API_KEY!,
  httpAgent: agent,
});

Pagination Optimization

async function* paginatedClickUpList<T>(
  fetcher: (cursor?: string) => Promise<{ data: T[]; nextCursor?: string }>
): AsyncGenerator<T

ClickUp Production Checklist

Overview

Complete checklist for deploying ClickUp integrations to production.

Prerequisites

• Staging environment tested and verified
• Production API keys available
• Deployment pipeline configured
• Monitoring and alerting ready

Instructions

Step 1: Pre-Deployment Configuration

• [ ] Production API keys in secure vault
• [ ] Environment variables set in deployment platform
• [ ] API key scopes are minimal (least privilege)
• [ ] Webhook endpoints configured with HTTPS
• [ ] Webhook secrets stored securely

Step 2: Code Quality Verification

• [ ] All tests passing (npm test)
• [ ] No hardcoded credentials
• [ ] Error handling covers all ClickUp error types
• [ ] Rate limiting/backoff implemented
• [ ] Logging is production-appropriate

Step 3: Infrastructure Setup

• [ ] Health check endpoint includes ClickUp connectivity
• [ ] Monitoring/alerting configured
• [ ] Circuit breaker pattern implemented
• [ ] Graceful degradation configured

Step 4: Documentation Requirements

• [ ] Incident runbook created
• [ ] Key rotation procedure documented
• [ ] Rollback procedure documented
• [ ] On-call escalation path defined

Step 5: Deploy with Gradual Rollout

# Pre-flight checks
curl -f https://staging.example.com/health
curl -s https://status.clickup.com

# Gradual rollout - start with canary (10%)
kubectl apply -f k8s/production.yaml
kubectl set image deployment/clickup-integration app=image:new --record
kubectl rollout pause deployment/clickup-integration

# Monitor canary traffic for 10 minutes
sleep 600
# Check error rates and latency before continuing

# If healthy, continue rollout to 50%
kubectl rollout resume deployment/clickup-integration
kubectl rollout pause deployment/clickup-integration
sleep 300

# Complete rollout to 100%
kubectl rollout resume deployment/clickup-integration
kubectl rollout status deployment/clickup-integration

Output

• Deployed ClickUp integration
• Health checks passing
• Monitoring active
• Rollback procedure documented

Error Handling

Examples

Health Check Implementation

async function healthCheck(): Promise<{ status: string; clickup: any }> {
  cons

ClickUp Rate Limits

Overview

Handle ClickUp rate limits gracefully with exponential backoff and idempotency.

Prerequisites

• ClickUp SDK installed
• Understanding of async/await patterns
• Access to rate limit headers

Instructions

Step 1: Understand Rate Limit Tiers

Step 2: Implement Exponential Backoff with Jitter

async function withExponentialBackoff<T>(
  operation: () => Promise<T>,
  config = { maxRetries: 5, baseDelayMs: 1000, maxDelayMs: 32000, jitterMs: 500 }
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error: any) {
      if (attempt === config.maxRetries) throw error;
      const status = error.status || error.response?.status;
      if (status !== 429 && (status < 500 || status >= 600)) throw error;

      // Exponential delay with jitter to prevent thundering herd
      const exponentialDelay = config.baseDelayMs * Math.pow(2, attempt);
      const jitter = Math.random() * config.jitterMs;
      const delay = Math.min(exponentialDelay + jitter, config.maxDelayMs);

      console.log(`Rate limited. Retrying in ${delay.toFixed(0)}ms...`);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

Step 3: Add Idempotency Keys

import { v4 as uuidv4 } from 'uuid';
import crypto from 'crypto';

// Generate deterministic key from operation params (for safe retries)
function generateIdempotencyKey(operation: string, params: Record<string, any>): string {
  const data = JSON.stringify({ operation, params });
  return crypto.createHash('sha256').update(data).digest('hex');
}

async function idempotentRequest<T>(
  client: ClickUpClient,
  params: Record<string, any>,
  idempotencyKey?: string  // Pass existing key for retries
): Promise<T> {
  // Use provided key (for retries) or generate deterministic key from params
  const key = idempotencyKey || generateIdempotencyKey(params.method || 'POST', params);
  return client.request({
    ...params,
    headers: { 'Idempotency-Key': key, ...params.headers },
  });
}

Output

• Reliable API calls with automatic retry
• Idempotent requests preventing duplicates
• Rate limit headers properly handled

Error Handling

my-clickup-project/
├── src/
│   ├── clickup/
│   │   ├── client.ts           # Singleton client wrapper
│   │   ├── config.ts           # Environment configuration
│   │   ├── types.ts            # TypeScript types
│   │   ├── errors.ts           # Custom error classes
│   │   └── handlers/
│   │       ├── webhooks.ts     # Webhook handlers
│   │       └── events.ts       # Event processing
│   ├── services/
│   │   └── clickup/
│   │       ├── index.ts        # Service facade
│   │       ├── sync.ts         # Data synchronization
│   │       └── cache.ts        # Caching layer
│   ├── api/
│   │   └── clickup/
│   │       └── webhook.ts      # Webhook endpoint
│   └── jobs/
│       └── clickup/
│           └── sync.ts         # Background sync job
├── tests/
│   ├── unit/
│   │   └── clickup/
│   └── integration/
│       └── clickup/
├── config/
│   ├── clickup.development.json
│   ├── clickup.staging.json
│   └── clickup.production.json
└── docs/
    └── clickup/
        ├── SETUP.md
        └── RUNBOOK.md

┌─────────────────────────────────────────┐
│             API Layer                    │
│   (Controllers, Routes, Webhooks)        │
├─────────────────────────────────────────┤
│           Service Layer                  │
│  (Business Logic, Orchestration)         │
├─────────────────────────────────────────┤
│          ClickUp Layer        │
│   (Client, Types, Error Handling)        │
├─────────────────────────────────────────┤
│         Infrastructure Layer             │
│    (Cache, Queue, Monitoring)            │
└─────────────────────────────────────────┘

// src/clickup/client.ts
export class ClickUpService {
  private client: ClickUpClient;
  private cache: Cache;
  private monitor: Monitor;

  constructor(config: ClickUpConfig) {
    this.client = new ClickUpClient(config);
    this.cache = new Cache(config.cacheOptions);
    this.monitor = new Monitor('clickup');
  }

  async get(id: string): Promise<Resource> {
    return this.cache.getOrFetch(id, () =>
      this.monitor.track('get', () => this.client.get(id))
    );
  }
}

// src/clickup/errors.ts
export class ClickUpServiceError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly retryable: boolean,
    public readonly originalError?: Error
  ) {
    super(message);
    this.name = 'ClickUpServiceError';
  }

// src/clickup/client.ts
import { ClickUpClient } from '@clickup/sdk';

let instance: ClickUpClient | null = null;

export function getClickUpClient(): ClickUpClient {
  if (!instance) {
    instance = new ClickUpClient({
      apiKey: process.env.CLICKUP_API_KEY!,
      // Additional options
    });
  }
  return instance;
}

import { ClickUpError } from '@clickup/sdk';

async function safeClickUpCall<T>(
  operation: () => Promise<T>
): Promise<{ data: T | null; error: Error | null }> {
  try {
    const data = await operation();
    return { data, error: null };
  } catch (err) {
    if (err instanceof ClickUpError) {
      console.error({
        code: err.code,
        message: err.message,
      });
    }
    return { data: null, error: err as Error };
  }
}

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  backoffMs = 1000
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === maxRetries) throw err;
      const delay = backoffMs * Math.pow(2, attempt - 1);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

const clients = new Map<string, ClickUpClient>();

export function getClientForTenant(tenantId: string): ClickUpClient {
  if (!clients.has(tenantId)) {
    const apiKey = getTenantApiKey(tenantId);
    clients.set(tenantId, new ClickUpClient({ apiKey }));
  }
  return clients

# .env (NEVER commit to git)
CLICKUP_API_KEY=sk_live_***
CLICKUP_SECRET=***

# .gitignore
.env
.env.local
.env.*.local

# 1. Generate new key in ClickUp dashboard
# 2. Update environment variable
export CLICKUP_API_KEY="new_key_here"

# 3. Verify new key works
curl -H "Authorization: Bearer ${CLICKUP_API_KEY}" \
  https://api.clickup.com/health

# 4. Revoke old key in dashboard

const clients = {
  reader: new ClickUpClient({
    apiKey: process.env.CLICKUP_READ_KEY,
  }),
  writer: new ClickUpClient({
    apiKey: process.env.CLICKUP_WRITE_KEY,
  }),
};

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string, signature: string, secret: string
): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

interface AuditEntry {
  timestamp: Date;
  action: string;
  userId: string;
  resource: string;
  result: 'success' | 'failure';
  metadata?: Re

npm list @clickup/sdk
npm view @clickup/sdk version

open https://github.com/clickup/sdk/releases

git checkout -b upgrade/clickup-sdk-vX.Y.Z
npm install @clickup/sdk@latest
npm test

// Before (v1.x)
import { Client } from '@clickup/sdk';

// After (v2.x)
import { ClickUpClient } from '@clickup/sdk';

// Before (v1.x)
const client = new Client({ key: 'xxx' });

// After (v2.x)
const client = new ClickUpClient({
  apiKey: 'xxx',
});

npm install @clickup/sdk@1.x.x --save-exact

// Monitor for deprecation warnings in development
if (process.env.NODE_ENV === 'development') {
  process.on('warning', (warning) => {
    if (warning.name === 'DeprecationWarning') {
      console.warn('[ClickUp]', warning.message);
      // Log to tracking system for proactive updates
    }
  });
}

// Common deprecation patterns to watch for:
// - Renamed methods: client.oldMethod() -> client.newMethod()
// - Changed parameters: { key: 'x' } -> { apiKey: 'x' }
// - Removed features: Check release notes before upgrading

import express from 'express';
import crypto from 'crypto';

const app = express();

// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/clickup',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['x-clickup-signature'] as string;
    const timestamp = req.headers['x-clickup-timestamp'] as string;

    if (!verifyClickUpSignature(req.body, signature, timestamp)) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    const event = JSON.parse(req.body.toString());
    await handleClickUpEvent(event);

    res.status(200).json({ received: true });
  }
);

function verifyClickUpSignature(
  payload: Buffer,
  signature: string,
  timestamp: string
): boolean {
  const secret = process.env.CLICKUP_WEBHOOK_SECRET!;

  // Reject old timestamps (replay attack protection)
  const timestampAge = Date.now() - parseInt(timestamp) * 1000;
  if (timestampAge > 300000) { // 5 minutes
    console.error('Webhook timestamp too old');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload.toString()}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

type ClickUpEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';

interface ClickUpEvent {
  id: string;
  type: ClickUpEventType;
  data: Record<string, any>;
  created: string;
}

const eventHandlers: Record<ClickUpEventType, (data: any) => Promise<void>> = {
  'resource.created': async (data) => { /* handle */ },
  'resource.updated': async (data) => { /* handle */ },
  'resource.deleted': async (data) => { /* handle */ }
};

async function handleClickUpEvent(event: ClickUpEvent): Promise<void> {
  const handler = eventHandlers[event.type];

  if (!handler) {
    console.log(`Unhandled event type: ${event.type}`);
    return;
  }

  try {
    await handler(event.data);
    console.log(`Processed ${event.type}: ${event.id}`);
  } catch (error) {
    console.error(`Failed to proc