Comprehensive API Guide

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

{% hint style="success" %} 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. {% endhint %}

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 Settings → Developer → Personal Access Tokens
2. Click Generate New Token
3. Copy and securely store your token
4. 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 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_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: support@taskade.com
• 📚 Help Center: taskade.com/learn

{% hint style="info" %} Need more help? Contact our support team for assistance with API integration or enterprise API requirements. {% endhint %}