TaskFlow API Documentation

Base URL

All API requests must be made over HTTPS. HTTP requests will be rejected.

Production https://api.taskflow.io/v2

Sandbox https://sandbox.taskflow.io/v2

Authentication

All API requests require a Bearer token in the Authorization header. Generate tokens from your dashboard — they expire after 90 days.

🔐 Authorization Header

Include your API key with every request. Never expose API keys in client-side or public code.

HTTP Header

Authorization: Bearer tf_live_xxxxxxxxxxxxxxxxxxxx

cURL Example

curl -X GET \
  https://api.taskflow.io/v2/tasks \
  -H "Authorization: Bearer tf_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Rate Limits

Requests are limited per API key. Exceeding limits returns a 429 Too Many Requests response.

1,000

Requests / minute — Free plan

10,000

Requests / minute — Pro plan

ℹ️

Rate limit headers are returned with every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Tasks

Create, read, update, and delete tasks. Every task belongs to a project and can be assigned to a team member.

GET /tasks List all tasks

Returns a paginated list of tasks for the authenticated workspace.

Query Parameters

Parameter	Type	Description
project_idoptional	string	Filter tasks by project ID.
statusoptional	string	Filter by status: `open`, `in_progress`, `done`.
limitoptional	integer	Results per page. Default: `20`. Max: `100`.
pageoptional	integer	Page number. Default: `1`.

Response

200 OK

JSON

{
  "data": [
    {
      "id": "task_8f3kd92",
      "title": "Design landing page mockup",
      "status": "in_progress",
      "priority": "high",
      "assignee_id": "usr_4j2nm01",
      "project_id": "proj_1a9xk33",
      "due_date": "2025-04-15T00:00:00Z",
      "created_at": "2025-03-01T09:14:22Z"
    }
  ],
  "pagination": {
    "total": 84,
    "page": 1,
    "limit": 20,
    "has_more": true
  }
}

POST /tasks Create a task

Creates a new task in the specified project.

Request Body

Field	Type	Description
titlerequired	string	Task title. Max 255 characters.
project_idrequired	string	ID of the project this task belongs to.
descriptionoptional	string	Detailed description. Supports Markdown.
priorityoptional	string	One of `low`, `medium`, `high`, `urgent`. Default: `medium`.
assignee_idoptional	string	User ID to assign the task to.
due_dateoptional	string (ISO 8601)	Deadline, e.g. `2025-04-30T00:00:00Z`.

cURL Request

curl -X POST \
  https://api.taskflow.io/v2/tasks \
  -H "Authorization: Bearer tf_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Design landing page mockup",
    "project_id": "proj_1a9xk33",
    "priority": "high",
    "due_date": "2025-04-15T00:00:00Z"
  }'

201 Created

JSON

{
  "data": {
    "id": "task_9a1bc74",
    "title": "Design landing page mockup",
    "status": "open",
    "priority": "high",
    "project_id": "proj_1a9xk33",
    "due_date": "2025-04-15T00:00:00Z",
    "created_at": "2025-03-06T10:00:00Z"
  }
}

PUT /tasks/{id} Update a task

Updates fields on an existing task. Only include fields you wish to change.

cURL Request

curl -X PUT \
  https://api.taskflow.io/v2/tasks/task_9a1bc74 \
  -H "Authorization: Bearer tf_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "done" }'

DELETE /tasks/{id} Delete a task

Permanently deletes a task. This action cannot be undone.

⚠️

Irreversible. Deleting a task also removes all associated comments, attachments, and activity history.

cURL Request

curl -X DELETE \
  https://api.taskflow.io/v2/tasks/task_9a1bc74 \
  -H "Authorization: Bearer tf_live_xxxx"

Projects

Projects are containers for tasks and team members. Each workspace can have unlimited projects.

GET /projects List all projects

Returns all projects in the authenticated workspace.

JSON Response

{
  "data": [
    {
      "id": "proj_1a9xk33",
      "name": "Website Redesign",
      "status": "active",
      "task_count": 12,
      "created_at": "2025-01-10T08:00:00Z"
    }
  ]
}

POST /projects Create a project

Creates a new project in the workspace.

Field	Type	Description
namerequired	string	Project name. Max 100 characters.
descriptionoptional	string	Short description of the project.
coloroptional	string (hex)	Label color, e.g. `#2563eb`. Default: `#64748b`.

Users

Retrieve and manage workspace members. Users can be assigned to tasks and projects.

GET /users List workspace members

Returns all users in the current workspace.

JSON Response

{
  "data": [
    {
      "id": "usr_4j2nm01",
      "name": "Amara Osei",
      "email": "[email protected]",
      "role": "admin",
      "joined_at": "2024-11-05T14:22:00Z"
    }
  ]
}

GET /users/{id} Get a single user

Returns full profile details for a single workspace member by their user ID.

Error Codes

All errors return a consistent JSON body with a machine-readable code and a human-readable message.

HTTP Status	Code	Description
200	success	Request completed successfully.
201	created	Resource created successfully.
400	invalid_request	Missing or malformed parameters.
401	unauthorized	Invalid or expired API key.
403	forbidden	Insufficient permissions for this resource.
404	not_found	Requested resource does not exist.
429	rate_limited	Too many requests. Retry after the reset window.
500	server_error	Internal server error. Contact support.

Error Response Example

{
  "error": {
    "code": "invalid_request",
    "message": "The field 'title' is required and cannot be empty.",
    "request_id": "req_7x2nm019kd"
  }
}

Changelog

Recent updates to the TaskFlow API.

Version	Date	Changes
v2.1	March 2025	Added `priority` field to tasks. Increased Pro rate limits to 10,000 req/min.
v2.0	Jan 2025	Introduced Projects and Users endpoints. Breaking: `assignee` renamed to `assignee_id`.
v1.0	Oct 2024	Initial release with Tasks CRUD.