Getting Started

REST API Guide

10 min readStart here
Getting Started

Build powerful integrations with Taskade's REST API. Access projects, tasks, agents, and more programmatically with full CRUD operations.


Taskade's API provides programmatic access to core platform features. Whether you're building custom integrations or automating workflows, our RESTful API offers the flexibility you need.

API Overview

The Taskade API is a RESTful web service that provides programmatic access to Taskade features.

Key Features

  • RESTful Design: Standard HTTP methods and status codes
  • Secure Authentication: OAuth 2.0 and Personal Access Token authentication
  • Complete CRUD Operations: Full create, read, update, delete functionality
  • Comprehensive Documentation: Detailed endpoint documentation

API Base URL

Base URL: https://www.taskade.com/api/v1
Authentication: Bearer token
Content-Type: application/json

Authentication

Personal Access Token Authentication

Simple authentication for server-to-server applications:

Bash
# Using Personal Access Token in header
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     https://www.taskade.com/api/v1/workspaces
Obtaining a Personal Access Token
  1. Go to taskade.com/settings/api.
  2. Click Create new token and give it a descriptive name.
  3. Copy and securely store your token — it starts with the tskdp_ prefix (you can hold up to 5 tokens per account).
  4. Use the token in the Authorization header.

See the Authentication guide for OAuth 2.0 and full details.

OAuth 2.0 Authentication

Secure authentication for user-facing applications:

Bash
# Authorization URL
https://www.taskade.com/oauth2/authorize

# Token URL  
https://www.taskade.com/oauth2/token

Core API Resources


Looking for bundle export/import? The four /bundles/* endpoints (export or import a Taskade Genesis app as a portable bundle) are documented on the Bundles & App Kits page.

Workspaces API

Manage workspaces and their contents:

Get All Workspaces
Bash
GET /workspaces
Javascript
// JavaScript example
const getWorkspaces = async (token) => {
  const response = await fetch('https://www.taskade.com/api/v1/workspaces', {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  });
  return response.json();
};
Python
# Python example
import requests

def get_workspaces(token):
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    response = requests.get('https://www.taskade.com/api/v1/workspaces', headers=headers)
    return response.json()
Get Workspace Folders
Bash
GET /workspaces/{workspaceId}/folders
Create Project in Workspace
Bash
POST /workspaces/{workspaceId}/projects
Content-Type: application/json

{
  "contentType": "text/markdown",
  "content": "# My New Project\n\n- Task 1\n- Task 2"
}

Folders API

Manage folders (subspaces) and their contents:

Get Folder Projects
Bash
GET /folders/{folderId}/projects
Get Folder Agents
Bash
GET /folders/{folderId}/agents
Create Agent in Folder
Bash
POST /folders/{folderId}/agents
Content-Type: application/json

{
  "name": "Customer Support Agent",
  "data": {
    "type": "template",
    "template": {
      "type": "CustomerSupport"
    }
  }
}
Generate Agent with AI
Bash
POST /folders/{folderId}/agent-generate
Content-Type: application/json

{
  "text": "Create an agent that helps with customer support questions"
}
Get Folder Media Files
Bash
GET /folders/{folderId}/medias
Get Folder Project Templates
Bash
GET /folders/{folderId}/project-templates

Projects API

Comprehensive project management:

Get Project
Bash
GET /projects/{projectId}
Create Project
Bash
POST /projects
Content-Type: application/json

{
  "folderId": "folder_123",
  "contentType": "text/markdown",
  "content": "# Project Title\n\n- First task\n- Second task"
}
Complete Project
Bash
POST /projects/{projectId}/complete
Restore Project
Bash
POST /projects/{projectId}/restore
Copy Project
Bash
POST /projects/{projectId}/copy
Content-Type: application/json

{
  "folderId": "destination_folder_id",
  "projectTitle": "Copied Project Name"
}
Create Project from Template
Bash
POST /projects/from-template
Content-Type: application/json

{
  "folderId": "folder_123",
  "templateId": "template_456"
}
Get Project Members
Bash
GET /projects/{projectId}/members?limit=20&page=1
Get Project Fields
Bash
GET /projects/{projectId}/fields
Bash
GET /projects/{projectId}/shareLink
Bash
PUT /projects/{projectId}/shareLink
Get Project Blocks
Bash
GET /projects/{projectId}/blocks?limit=100
Get Project Tasks
Bash
GET /projects/{projectId}/tasks?limit=100

Tasks API

Comprehensive task management:

Get Task
Bash
GET /projects/{projectId}/tasks/{taskId}
Create Tasks
Bash
POST /projects/{projectId}/tasks/
Content-Type: application/json

{
  "tasks": [
    {
      "contentType": "text/markdown",
      "content": "New task content",
      "placement": "beforeend"
    }
  ]
}
Javascript
// Create multiple tasks
const createTasks = async (projectId, tasks) => {
  const response = await fetch(
    `https://www.taskade.com/api/v1/projects/${projectId}/tasks/`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        tasks: tasks.map(content => ({
          contentType: 'text/markdown',
          content: content,
          placement: 'beforeend'
        }))
      })
    }
  );
  return response.json();
};
Update Task
Bash
PUT /projects/{projectId}/tasks/{taskId}
Content-Type: application/json

{
  "contentType": "text/markdown",
  "content": "Updated task content"
}
Delete Task
Bash
DELETE /projects/{projectId}/tasks/{taskId}
Complete Task
Bash
POST /projects/{projectId}/tasks/{taskId}/complete
Mark Task Incomplete
Bash
POST /projects/{projectId}/tasks/{taskId}/uncomplete
Move Task
Bash
PUT /projects/{projectId}/tasks/{taskId}/move
Content-Type: application/json

{
  "target": {
    "taskId": "target_task_id",
    "position": "afterend"
  }
}

Position options: beforebegin, afterbegin, beforeend, afterend

Get Task Assignees
Bash
GET /projects/{projectId}/tasks/{taskId}/assignees
Update Task Assignees
Bash
PUT /projects/{projectId}/tasks/{taskId}/assignees
Content-Type: application/json

{
  "handles": ["user_handle_1", "user_handle_2"]
}
Remove Task Assignee
Bash
DELETE /projects/{projectId}/tasks/{taskId}/assignees/{assigneeHandle}
Get Task Date
Bash
GET /projects/{projectId}/tasks/{taskId}/date
Set Task Date
Bash
PUT /projects/{projectId}/tasks/{taskId}/date
Content-Type: application/json

{
  "start": {
    "date": "2024-12-31",
    "time": "17:00:00",
    "timezone": "America/New_York"
  },
  "end": {
    "date": "2025-01-15",
    "time": "17:00:00",
    "timezone": "America/New_York"
  }
}
Delete Task Date
Bash
DELETE /projects/{projectId}/tasks/{taskId}/date
Get Task Note
Bash
GET /projects/{projectId}/tasks/{taskId}/note
Update Task Note
Bash
PUT /projects/{projectId}/tasks/{taskId}/note
Content-Type: application/json

{
  "type": "text/markdown",
  "value": "This is a note for the task"
}
Delete Task Note
Bash
DELETE /projects/{projectId}/tasks/{taskId}/note
Get Task Field Values
Bash
GET /projects/{projectId}/tasks/{taskId}/fields
Get Specific Field Value
Bash
GET /projects/{projectId}/tasks/{taskId}/fields/{fieldId}
Update Field Value
Bash
PUT /projects/{projectId}/tasks/{taskId}/fields/{fieldId}
Content-Type: application/json

{
  "value": "field_value"
}
Delete Field Value
Bash
DELETE /projects/{projectId}/tasks/{taskId}/fields/{fieldId}

Agents API

Manage AI agents:

Get Agent
Bash
GET /agents/{agentId}
Update Agent
Bash
PATCH /agents/{agentId}
Content-Type: application/json

{
  "name": "Updated Agent Name",
  "data": {
    "description": "Updated agent description"
  }
}
Delete Agent
Bash
DELETE /agents/{agentId}
Enable Public Access
Bash
PUT /agents/{agentId}/publicAccess
Get Public Agent Settings
Bash
GET /agents/{agentId}/public-agent
Update Public Agent Settings
Bash
PATCH /agents/{agentId}/public-agent
Content-Type: application/json

{
  "preferences": {
    "mode": "chatbot",
    "theme": "light",
    "hideBranding": false
  }
}
Get Public Agent by Public ID
Bash
GET /public-agents/{publicAgentId}
Add Project to Agent Knowledge
Bash
POST /agents/{agentId}/knowledge/project
Content-Type: application/json

{
  "projectId": "project_123"
}
Add Media to Agent Knowledge
Bash
POST /agents/{agentId}/knowledge/media
Content-Type: application/json

{
  "mediaId": "media_456"
}
Remove Project from Agent Knowledge
Bash
DELETE /agents/{agentId}/knowledge/project/{projectId}
Remove Media from Agent Knowledge
Bash
DELETE /agents/{agentId}/knowledge/media/{mediaId}
Get Agent Conversations
Bash
GET /agents/{agentId}/convos/?limit=20&page=1
Get Specific Conversation
Bash
GET /agents/{agentId}/convos/{convoId}

Media API

Manage uploaded files:

Get Media
Bash
GET /medias/{mediaId}
Delete Media
Bash
DELETE /medias/{mediaId}

User Projects API

Access the authenticated user's projects:

Get My Projects
Bash
GET /me/projects?limit=100&page=1&sort=viewed-desc

Sort options: viewed-asc, viewed-desc

Error Handling

HTTP Status Codes

  • 200 OK: Request successful
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded — see Rate Limits
  • 4XX: Client error (see response for details)

Error Response Format

Json
{
  "ok": false,
  "message": "Error description",
  "code": "ERROR_CODE",
  "statusMessage": "HTTP status message"
}

Error Handling Example

Javascript
// Robust error handling
const apiRequest = async (url, options = {}) => {
  const response = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      ...options.headers
    },
    ...options
  });
  
  const data = await response.json();
  
  if (!data.ok) {
    throw new Error(`API Error: ${data.message} (${data.code})`);
  }
  
  return data;
};

Rate Limits

Requests are rate-limited per endpoint. Exact ceilings aren't published and can change without notice — when you hit one, the 429 response itself tells you everything you need:

Header Meaning
x-rate-limit-limit Your total budget for the current window
x-rate-limit-remaining Requests left in the window (0 when you're blocked)
x-rate-limit-reset Seconds until the window reopens — schedule your retry from this

Retry-After is not sent, so don't wait for it. Wait out x-rate-limit-reset before retrying — earlier retries will also be rejected:

Javascript
const apiRequestWithRetry = async (url, options = {}, retries = 3) => {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const resetSec = Number(response.headers.get('x-rate-limit-reset'));
    const waitMs = resetSec > 0 ? resetSec * 1000 : 2 ** i * 1000;
    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error('Rate limit retries exhausted');
};

Two habits keep most integrations out of 429 territory entirely:

  • Batch instead of loop — bulk endpoints and array-accepting operations do in one request what a loop does in fifty.
  • Spread scheduled work — cron jobs that all fire at :00 burst past limits that a staggered schedule never touches. Bundle import/export runs under tighter limits than regular reads and writes, so schedule bulk transfers with extra headroom.

Pagination

Many endpoints support pagination using cursor-based or page-based approaches:

Page-based Pagination

Bash
GET /me/projects?limit=20&page=2

Cursor-based Pagination (Tasks/Blocks)

Bash
# Get tasks after a specific task
GET /projects/{projectId}/tasks?limit=100&after={taskId}

# Get tasks before a specific task
GET /projects/{projectId}/tasks?limit=100&before={taskId}

Code Examples

Complete Workflow Example

Javascript
// Complete example: Create a project and add tasks
const createProjectWithTasks = async (folderId, projectName, tasks) => {
  const headers = {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  };
  
  // Step 1: Create the project
  const projectContent = `# ${projectName}\n\n` + 
    tasks.map(t => `- ${t}`).join('\n');
  
  const projectResponse = await fetch(
    'https://www.taskade.com/api/v1/projects',
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        folderId: folderId,
        contentType: 'text/markdown',
        content: projectContent
      })
    }
  );
  
  const projectData = await projectResponse.json();
  
  if (!projectData.ok) {
    throw new Error(`Failed to create project: ${projectData.message}`);
  }
  
  return projectData.item;
};

// Usage
const project = await createProjectWithTasks(
  'folder_123',
  'My New Project',
  ['Task 1', 'Task 2', 'Task 3']
);
console.log('Created project:', project.id);

Agent Integration Example

Javascript
// Create an agent and add knowledge
const setupAgent = async (folderId, agentName, projectIds) => {
  const headers = {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  };
  
  // Step 1: Create the agent
  const agentResponse = await fetch(
    `https://www.taskade.com/api/v1/folders/${folderId}/agents`,
    {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: agentName,
        data: {
          type: 'template',
          template: {
            type: 'Researcher'
          }
        }
      })
    }
  );
  
  const agentData = await agentResponse.json();
  const agentId = agentData.item.id;
  
  // Step 2: Add projects to knowledge base
  for (const projectId of projectIds) {
    await fetch(
      `https://www.taskade.com/api/v1/agents/${agentId}/knowledge/project`,
      {
        method: 'POST',
        headers,
        body: JSON.stringify({ projectId })
      }
    );
  }
  
  return agentData.item;
};

Python Example

Python
import requests

API_BASE = 'https://www.taskade.com/api/v1'

class TaskadeClient:
    def __init__(self, token):
        self.token = token
        self.headers = {
            'Authorization': f'Bearer {token}',
            'Content-Type': 'application/json'
        }
    
    def get_workspaces(self):
        """Get all workspaces"""
        response = requests.get(f'{API_BASE}/workspaces', headers=self.headers)
        return response.json()
    
    def get_folder_projects(self, folder_id):
        """Get all projects in a folder"""
        response = requests.get(
            f'{API_BASE}/folders/{folder_id}/projects',
            headers=self.headers
        )
        return response.json()
    
    def create_project(self, folder_id, content):
        """Create a new project"""
        response = requests.post(
            f'{API_BASE}/projects',
            headers=self.headers,
            json={
                'folderId': folder_id,
                'contentType': 'text/markdown',
                'content': content
            }
        )
        return response.json()
    
    def complete_task(self, project_id, task_id):
        """Mark a task as complete"""
        response = requests.post(
            f'{API_BASE}/projects/{project_id}/tasks/{task_id}/complete',
            headers=self.headers
        )
        return response.json()
    
    def get_agent(self, agent_id):
        """Get an agent"""
        response = requests.get(
            f'{API_BASE}/agents/{agent_id}',
            headers=self.headers
        )
        return response.json()

# Usage
client = TaskadeClient('YOUR_ACCESS_TOKEN')
workspaces = client.get_workspaces()
print(f"Found {len(workspaces['items'])} workspaces")

Best Practices

Security

  • Store API tokens securely (environment variables, secret management)
  • Use HTTPS for all API calls
  • Implement proper error handling
  • Never expose tokens in client-side code

Performance

  • Use pagination for large result sets
  • Cache responses when appropriate
  • Implement exponential backoff for retries
  • Batch operations when possible

Data Management

  • Validate data before sending to API
  • Handle partial failures gracefully
  • Implement proper logging and monitoring

Support and Resources

Documentation

Getting Help


Need more help? Contact our support team for assistance with API integration or enterprise API requirements.

PreviousAPI OverviewNextAction API Guide