Taskade API Overview

The Taskade API lets your code read and change workspaces, projects, tasks, AI agents, media, and app bundles over HTTPS. This page starts the Taskade API documentation: one first call, every API surface, and the path that fits your task.

Page type: Concept. Read it to learn what this is and when to use it.

TL;DR: Create a personal access token at taskade.com/settings/api. Send it as Authorization: Bearer $TASKADE_TOKEN to https://www.taskade.com/api/v1. For AI clients, connect to the hosted MCP server at https://www.taskade.com/mcp.

Make your first call in 30 seconds

One token and one curl command return the workspaces that your account can use.

Warning: Keep the token out of source code and out of the browser. A personal access token has no scopes. It can do everything that your account can do.

1. Open taskade.com/settings/api.
2. Under Personal access tokens, click Create token. Type a name, then click Create.
3. Copy the token. Taskade shows it one time only.
4. Save the token in your terminal:

export TASKADE_TOKEN="tskdp_your_token_here"

5. List your workspaces:

curl -s https://www.taskade.com/api/v1/workspaces \
  -H "Authorization: Bearer $TASKADE_TOKEN"

The response lists each workspace with its id and name:

{
  "ok": true,
  "items": [
    { "id": "Wk3rT9pLmQ2vXa7c", "name": "My Workspace" }
  ]
}

You are done when the response holds "ok": true and the names of your workspaces. To create a project and add tasks next, follow the Quickstart.

Taskade API surfaces

Every surface below uses the workspaces that your Taskade account already has. Pick one by what calls what.

Choose your path

Use REST API v1 for scripts and back-end jobs. Use the Action API v2 or MCP when an AI model calls Taskade. Use webhooks when Taskade must call you.

Base URL and authentication

Each API has one base URL. Every request carries a token in the Authorization header.

Send the token as a bearer token:

curl -s https://www.taskade.com/api/v1/me/projects \
  -H "Authorization: Bearer $TASKADE_TOKEN"

A list call returns { "ok": true, "items": [...] }. A single-item call returns { "ok": true, "item": {...} }.

Core API resources

The REST API v1 has one table for each resource. Each path links to its generated reference page, with the full parameters and responses. Paths are relative to https://www.taskade.com/api/v1.

Note: The generated REST catalog and Actions catalog come from the committed OpenAPI specs. If a hand-written example differs from a catalog page, the catalog page is correct.

Workspaces

Workspaces hold your folders and projects.

Folders

Folders (subspaces) hold projects, agents, and media inside a workspace.

Projects

A project holds tasks, notes, and structured data.

Tasks

A task is one item in a project. It can carry assignees, a date, a note, and field values.

AI Agents

An AI agent answers chats and runs work with its own instructions and knowledge.

Media

Media files are the uploads in a workspace.

Bundles

A bundle is a portable copy of a whole app or workspace. See Bundles & App Kits.

User projects

Your own recent projects, across workspaces.

Errors

Every error returns "ok": false and an upper-case code. Branch on ok and code. Do not parse message.

HTTP status codes

Error response format

Every error carries ok, message, code, and statusMessage. A missing token returns 401:

{
  "ok": false,
  "message": "Unauthorized",
  "code": "UNAUTHORIZED",
  "statusMessage": "Unauthorized"
}

A plan error can also carry featureId, the plan feature that the call needs. The bundle export returns "featureId": "space.bundle.export" with its 402.

Fix common errors

Match the code in the response to a fix.

Code examples

The same calls in three runtimes. Each example reads the token from the TASKADE_TOKEN environment variable.

JavaScript (Node.js 18 or later)

const API_BASE = 'https://www.taskade.com/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.TASKADE_TOKEN}`,
  'Content-Type': 'application/json',
};

// Get all workspaces
async function getWorkspaces() {
  const response = await fetch(`${API_BASE}/workspaces`, { headers });
  return response.json();
}

// Get project tasks
async function getProjectTasks(projectId) {
  const response = await fetch(`${API_BASE}/projects/${projectId}/tasks`, { headers });
  return response.json();
}

// Create a task at the end of a project
async function createTask(projectId, content) {
  const response = await fetch(`${API_BASE}/projects/${projectId}/tasks/`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      tasks: [{ contentType: 'text/markdown', content, placement: 'beforeend' }],
    }),
  });
  return response.json();
}

Python

Python 3 with the requests package.

import os
import requests

API_BASE = 'https://www.taskade.com/api/v1'
headers = {
    'Authorization': f"Bearer {os.environ['TASKADE_TOKEN']}",
    'Content-Type': 'application/json',
}

# Get all workspaces
def get_workspaces():
    response = requests.get(f'{API_BASE}/workspaces', headers=headers)
    return response.json()

# Get project tasks
def get_project_tasks(project_id):
    response = requests.get(f'{API_BASE}/projects/{project_id}/tasks', headers=headers)
    return response.json()

# Complete a task
def complete_task(project_id, task_id):
    response = requests.post(
        f'{API_BASE}/projects/{project_id}/tasks/{task_id}/complete',
        headers=headers,
    )
    return response.json()

cURL

Save the IDs that you use, then send the requests:

export FOLDER_ID="your_folder_id"
export AGENT_ID="your_agent_id"

# Get projects in a folder
curl -s "https://www.taskade.com/api/v1/folders/$FOLDER_ID/projects" \
  -H "Authorization: Bearer $TASKADE_TOKEN"

# Get an agent
curl -s "https://www.taskade.com/api/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $TASKADE_TOKEN"

A list call returns { "ok": true, "items": [...] }. A single-item call returns { "ok": true, "item": {...} }.

Best practices

Follow these rules to keep an integration safe, fast, and correct.

Security

• Store tokens in environment variables or a secret manager.
• Never put a token in client-side code or in a public repository.
• Use one token for each integration, so that you can revoke one without the others.
• Handle every error response.

Performance

• Page through large lists. Tasks and blocks use cursor pagination.
• Cache responses when the data permits it.
• Retry a 429 after the number of seconds in its Retry-After header.

Data management

• Validate data before you send it to the API.
• Record partial failures, and retry only the calls that failed.

Next steps

1. Make a full first integration: Quickstart creates a project and adds tasks in about five minutes.
2. Look up an endpoint: REST API reference lists every v1 endpoint with its parameters and responses.
3. Build AI tools: Action API guide gives one verb for each operation.
4. Connect an AI client: Hosted Taskade MCP has the setup for Claude, Cursor, VS Code, and ChatGPT.
5. Get help: search the Help Center, or email support@taskade.com.