TaskFlow API Documentation

Build powerful integrations with TaskFlow's RESTful API. Access projects, tasks, users, and more programmatically.

API Status: Operational

Introduction

The TaskFlow API is a RESTful API that allows you to integrate TaskFlow's project management capabilities into your applications. Our API follows standard HTTP conventions and returns JSON responses.

ℹī¸

Base URL

https://api.taskflow.com/v2

Key Features

  • RESTful architecture with predictable URLs
  • JSON request and response bodies
  • Standard HTTP status codes
  • OAuth 2.0 and API key authentication
  • Rate limiting and pagination
  • Comprehensive error messages
  • Real-time webhooks
  • SDKs for popular languages

Authentication

TaskFlow API supports two authentication methods: API Keys for server-to-server communication and OAuth 2.0 for user-facing applications.

API Key Authentication

Include your API key in the Authorization header:

Request Headers 
Authorization: Bearer your_api_key_here
Content-Type: application/json

OAuth 2.0

For user-facing applications, use OAuth 2.0 with the authorization code flow:

Authorization URL 
https://api.taskflow.com/oauth/authorize?
  client_id=your_client_id&
  redirect_uri=your_redirect_uri&
  response_type=code&
  scope=read write

Rate Limiting

API requests are rate limited to ensure fair usage and system stability.

Free Tier

1,000 requests/hour
Burst: 100 requests/minute

Pro Tier

10,000 requests/hour
Burst: 500 requests/minute

Enterprise

100,000 requests/hour
Burst: 2,000 requests/minute

Rate Limit Headers

Response Headers 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Error Handling

TaskFlow API uses conventional HTTP response codes and returns detailed error information in JSON format.

200

OK

Request succeeded

400

Bad Request

Invalid request parameters

401

Unauthorized

Invalid or missing authentication

403

Forbidden

Insufficient permissions

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

Error Response Format

Error Response 
{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ],
    "request_id": "req_1234567890"
  }
}

Projects

Projects are the top-level containers for organizing tasks and team collaboration.

GET
/projects
List Projects

Retrieve a list of projects accessible to the authenticated user.

Query Parameters

limit
integer
Number of results to return (1-100, default: 20)
offset
integer
Number of results to skip (default: 0)
status
string
Filter by status: active, completed, archived
Example Request 
curl -X GET "https://api.taskflow.com/v2/projects?limit=10&status=active" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
const response = await fetch('https://api.taskflow.com/v2/projects?limit=10&status=active', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
  }
});

const projects = await response.json();
import requests

headers = {
    'Authorization': 'Bearer your_api_key_here',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.taskflow.com/v2/projects',
    headers=headers,
    params={'limit': 10, 'status': 'active'}
)

projects = response.json()
Example Response 
{
  "data": [
    {
      "id": "proj_1234567890",
      "name": "Website Redesign",
      "description": "Complete overhaul of company website",
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-20T14:22:00Z",
      "owner": {
        "id": "user_0987654321",
        "name": "John Doe",
        "email": "john@company.com"
      },
      "team_id": "team_1122334455",
      "task_count": 24,
      "completed_tasks": 12,
      "progress": 50.0,
      "due_date": "2025-03-01T00:00:00Z",
      "tags": ["design", "frontend", "priority-high"]
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}
POST
/projects
Create Project

Create a new project.

Request Body

name
string
Project name (1-100 characters)
description
string
Project description (max 1000 characters)
team_id
string
ID of the team to assign the project to
due_date
string
Due date in ISO 8601 format
tags
array
Array of tag strings
Example Request 
curl -X POST "https://api.taskflow.com/v2/projects" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App Development",
    "description": "Build iOS and Android mobile applications",
    "team_id": "team_1122334455",
    "due_date": "2025-06-01T00:00:00Z",
    "tags": ["mobile", "ios", "android"]
  }'

Tasks

Tasks represent individual work items within projects.

GET
/projects/{project_id}/tasks
List Tasks

Retrieve tasks for a specific project.

Path Parameters

project_id
string
The ID of the project

Query Parameters

status
string
Filter by status: todo, in_progress, completed
assignee_id
string
Filter by assigned user ID
priority
string
Filter by priority: low, medium, high, urgent
Example Response 
{
  "data": [
    {
      "id": "task_9876543210",
      "title": "Design homepage mockup",
      "description": "Create wireframes and visual mockups for the new homepage",
      "status": "in_progress",
      "priority": "high",
      "created_at": "2025-01-16T09:15:00Z",
      "updated_at": "2025-01-18T11:30:00Z",
      "due_date": "2025-01-25T17:00:00Z",
      "assignee": {
        "id": "user_1357924680",
        "name": "Jane Smith",
        "email": "jane@company.com"
      },
      "project_id": "proj_1234567890",
      "tags": ["design", "homepage"],
      "time_estimate": 480,
      "time_spent": 240,
      "subtasks": [
        {
          "id": "subtask_1111111111",
          "title": "Create wireframes",
          "completed": true
        },
        {
          "id": "subtask_2222222222",
          "title": "Design visual mockups",
          "completed": false
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}

Users

Manage user accounts and profiles.

GET
/users/me
Get Current User

Retrieve information about the authenticated user.

Example Response 
{
  "id": "user_0987654321",
  "name": "John Doe",
  "email": "john@company.com",
  "avatar_url": "https://cdn.taskflow.com/avatars/user_0987654321.jpg",
  "role": "admin",
  "created_at": "2024-12-01T10:00:00Z",
  "last_active": "2025-01-20T15:30:00Z",
  "timezone": "America/New_York",
  "preferences": {
    "notifications": {
      "email": true,
      "push": true,
      "desktop": false
    },
    "theme": "light"
  },
  "subscription": {
    "plan": "pro",
    "status": "active",
    "expires_at": "2025-12-01T00:00:00Z"
  }
}

Teams

Manage teams and team memberships.

GET
/teams
List Teams

Retrieve teams that the authenticated user belongs to.

Example Response 
{
  "data": [
    {
      "id": "team_1122334455",
      "name": "Design Team",
      "description": "UI/UX designers and visual artists",
      "created_at": "2024-11-15T08:00:00Z",
      "member_count": 8,
      "project_count": 12,
      "owner": {
        "id": "user_0987654321",
        "name": "John Doe",
        "email": "john@company.com"
      },
      "members": [
        {
          "id": "user_1357924680",
          "name": "Jane Smith",
          "email": "jane@company.com",
          "role": "member",
          "joined_at": "2024-11-20T10:30:00Z"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1,
    "has_more": false
  }
}

Webhooks

Set up real-time notifications for events in your TaskFlow account.

Supported Events

project.created
New project created
project.updated
Project details changed
task.created
New task created
task.completed
Task marked as completed
user.invited
User invited to team
comment.added
Comment added to task
POST
/webhooks
Create Webhook

Create a new webhook endpoint.

Example Request 
curl -X POST "https://api.taskflow.com/v2/webhooks" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/taskflow",
    "events": ["task.created", "task.completed"],
    "secret": "your_webhook_secret"
  }'

SDKs

Official SDKs and libraries for popular programming languages.

🟨

JavaScript/Node.js

Official JavaScript SDK for browser and Node.js applications.

npm install @taskflow/sdk
Documentation GitHub
🐍

Python

Official Python SDK with async support.

pip install taskflow-sdk
Documentation PyPI
☕

Java

Official Java SDK for enterprise applications.

implementation 'com.taskflow:sdk:2.1.0'
Documentation Maven Central
🔷

Go

Official Go SDK with full API coverage.

go get github.com/taskflow/go-sdk
Documentation GitHub

Changelog

Recent updates and changes to the TaskFlow API.

2025-01-15
v2.1.0

New Features

  • Added search endpoint with full-text search capabilities
  • Introduced webhook support for real-time notifications
  • Added subtasks support in task objects

Improvements

  • Increased rate limits for Pro and Enterprise tiers
  • Enhanced error messages with more detailed information
  • Added time tracking fields to tasks
2024-12-20
v2.0.0

Breaking Changes

  • Updated authentication to use Bearer tokens
  • Changed date format to ISO 8601
  • Renamed several field names for consistency

New Features

  • Added teams endpoint
  • Introduced pagination for all list endpoints
  • Added OAuth 2.0 support

Support

Get help with the TaskFlow API.

📚

Documentation

Comprehensive guides and tutorials

View Docs
đŸ’Ŧ

Community Forum

Ask questions and share knowledge

Join Forum
đŸŽĢ

Support Tickets

Get direct help from our team

Contact Support
📊

API Status

Check current API status and uptime

View Status