REST API v1 Reference

Taskade REST API v1 reference — authenticate, then manage workspaces, projects, tasks, agents, folders, and media with full CRUD and copy-paste code examples.

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:

# 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:

# 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 Genesis app as a portable bundle) are documented on the Bundles & App Kits page.

Workspaces API

Manage workspaces and their contents:

Get All Workspaces

GET /workspaces

// 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 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

GET /workspaces/{workspaceId}/folders

Create Project in Workspace

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

GET /folders/{folderId}/projects

Get Folder Agents

GET /folders/{folderId}/agents

Create Agent in Folder

POST /folders/{folderId}/agents
Content-Type: application/json

{
  "name": "Customer Support Agent",
  "data": {
    "type": "template",
    "template": {
      "type": "CustomerSupport"
    }
  }
}

Generate Agent with AI

POST /folders/{folderId}/agent-generate
Content-Type: application/json

{
  "text": "Create an agent that helps with customer support questions"
}

Get Folder Media Files

GET /folders/{folderId}/medias

Get Folder Project Templates

GET /folders/{folderId}/project-templates

Projects API

Comprehensive project management:

Get Project

GET /projects/{projectId}

Create Project

POST /projects
Content-Type: application/json

{
  "folderId": "folder_123",
  "contentType": "text/markdown",
  "content": "# Project Title\n\n- First task\n- Second task"
}

Complete Project

POST /projects/{projectId}/complete

Restore Project

POST /projects/{projectId}/restore

Copy Project

POST /projects/{projectId}/copy
Content-Type: application/json

{
  "folderId": "destination_folder_id",
  "projectTitle": "Copied Project Name"
}

Create Project from Template

POST /projects/from-template
Content-Type: application/json

{
  "folderId": "folder_123",
  "templateId": "template_456"
}

Get Project Members

GET /projects/{projectId}/members?limit=20&page=1

Get Project Fields

GET /projects/{projectId}/fields

Get Project Share Link

GET /projects/{projectId}/shareLink

Enable Share Link

PUT /projects/{projectId}/shareLink

Get Project Blocks

GET /projects/{projectId}/blocks?limit=100

Get Project Tasks

GET /projects/{projectId}/tasks?limit=100

Tasks API

Comprehensive task management:

Get Task

GET /projects/{projectId}/tasks/{taskId}

Create Tasks

POST /projects/{projectId}/tasks/
Content-Type: application/json

{
  "tasks": [
    {
      "contentType": "text/markdown",
      "content": "New task content",
      "placement": "beforeend"
    }
  ]
}

// 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

PUT /projects/{projectId}/tasks/{taskId}
Content-Type: application/json

{
  "contentType": "text/markdown",
  "content": "Updated task content"
}

Delete Task

DELETE /projects/{projectId}/tasks/{taskId}

Complete Task

POST /projects/{projectId}/tasks/{taskId}/complete

Mark Task Incomplete

POST /projects/{projectId}/tasks/{taskId}/uncomplete

Move Task

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

GET /projects/{projectId}/tasks/{taskId}/assignees

Update Task Assignees

PUT /projects/{projectId}/tasks/{taskId}/assignees
Content-Type: application/json

{
  "handles": ["user_handle_1", "user_handle_2"]
}

Remove Task Assignee

DELETE /projects/{projectId}/tasks/{taskId}/assignees/{assigneeHandle}

Get Task Date

GET /projects/{projectId}/tasks/{taskId}/date

Set Task Date

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

DELETE /projects/{projectId}/tasks/{taskId}/date

Get Task Note

GET /projects/{projectId}/tasks/{taskId}/note

Update Task Note

PUT /projects/{projectId}/tasks/{taskId}/note
Content-Type: application/json

{
  "type": "text/markdown",
  "value": "This is a note for the task"
}

Delete Task Note

DELETE /projects/{projectId}/tasks/{taskId}/note

Get Task Field Values

GET /projects/{projectId}/tasks/{taskId}/fields

Get Specific Field Value

GET /projects/{projectId}/tasks/{taskId}/fields/{fieldId}

Update Field Value

PUT /projects/{projectId}/tasks/{taskId}/fields/{fieldId}
Content-Type: application/json

{
  "value": "field_value"
}

Delete Field Value

DELETE /projects/{projectId}/tasks/{taskId}/fields/{fieldId}

Agents API

Manage AI agents:

Get Agent

GET /agents/{agentId}

Update Agent

PATCH /agents/{agentId}
Content-Type: application/json

{
  "name": "Updated Agent Name",
  "data": {
    "description": "Updated agent description"
  }
}

Delete Agent

DELETE /agents/{agentId}

Enable Public Access

PUT /agents/{agentId}/publicAccess

Get Public Agent Settings

GET /agents/{agentId}/public-agent

Update Public Agent Settings

PATCH /agents/{agentId}/public-agent
Content-Type: application/json

{
  "preferences": {
    "mode": "chatbot",
    "theme": "light",
    "hideBranding": false
  }
}

Get Public Agent by Public ID

GET /public-agents/{publicAgentId}

Add Project to Agent Knowledge

POST /agents/{agentId}/knowledge/project
Content-Type: application/json

{
  "projectId": "project_123"
}

Add Media to Agent Knowledge

POST /agents/{agentId}/knowledge/media
Content-Type: application/json

{
  "mediaId": "media_456"
}

Remove Project from Agent Knowledge

DELETE /agents/{agentId}/knowledge/project/{projectId}

Remove Media from Agent Knowledge

DELETE /agents/{agentId}/knowledge/media/{mediaId}

Get Agent Conversations

GET /agents/{agentId}/convos/?limit=20&page=1

Get Specific Conversation

GET /agents/{agentId}/convos/{convoId}

Media API

Manage uploaded files:

Get Media

GET /medias/{mediaId}

Delete Media

DELETE /medias/{mediaId}

User Projects API

Access the authenticated user's projects:

Get My Projects

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

• 4XX: Client error (see response for details)

Error Response Format

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

Error Handling Example

// 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;
};

Pagination

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

Page-based Pagination

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

Cursor-based Pagination (Tasks/Blocks)

# 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

// 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

// 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

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

• API Reference: Full endpoint documentation in each resource section

• Authentication Guide: Personal Access Tokens

• OAuth Setup: OAuth Authentication

Getting Help

• Support: [email protected]

• Help Center: taskade.com/learn

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