Comprehensive API Guide

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

Go to Settings → Developer → Personal Access Tokens
Click Generate New Token
Copy and securely store your token
Use the token in the Authorization header

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

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 /projects/{projectId}/shareLink

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_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: help.taskade.com

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

PreviousLiving Intelligence API Overview NextWorkspaces

Last updated 8 days ago

API Overview

Key Features

API Base URL

Authentication

Personal Access Token Authentication

Obtaining a Personal Access Token

OAuth 2.0 Authentication

Core API Resources

Workspaces API

Get All Workspaces

Get Workspace Folders

Create Project in Workspace

Folders API

Get Folder Projects

Get Folder Agents

Create Agent in Folder

Generate Agent with AI

Get Folder Media Files

Get Folder Project Templates

Projects API

Get Project

Create Project

Complete Project

Restore Project

Copy Project

Create Project from Template

Get Project Members

Get Project Fields

Get Project Share Link

Enable Share Link

Get Project Blocks

Get Project Tasks

Tasks API

Get Task

Create Tasks

Update Task

Delete Task

Complete Task

Mark Task Incomplete

Move Task

Get Task Assignees

Update Task Assignees

Remove Task Assignee

Get Task Date

Set Task Date

Delete Task Date

Get Task Note

Update Task Note

Delete Task Note

Get Task Field Values

Get Specific Field Value

Update Field Value

Delete Field Value

Agents API

Get Agent

Update Agent

Delete Agent

Enable Public Access

Get Public Agent Settings

Update Public Agent Settings

Get Public Agent by Public ID

Add Project to Agent Knowledge

Add Media to Agent Knowledge

Remove Project from Agent Knowledge

Remove Media from Agent Knowledge

Get Agent Conversations

Get Specific Conversation

Media API

Get Media

Delete Media

User Projects API

Get My Projects

Error Handling

HTTP Status Codes

Error Response Format

Error Handling Example

Pagination

Page-based Pagination

Cursor-based Pagination (Tasks/Blocks)

Code Examples