Documentation

Everything you need to connect to the TaskFlow platform, manage tasks programmatically, and build AI-powered automations.

Getting Started

TaskFlow provides a full REST API that allows you to manage every aspect of your workspace programmatically. The API supports both browser-based access and API key authentication for external integrations.

Base URL

https://your-domain.com/api

Authentication

There are two ways to authenticate with the TaskFlow API:

Browser session — Full access when using the platform directly in a browser. No additional setup needed.
API Key — For external integrations, AI agents, and programmatic access. Include the key in the request header.

# Include your API key in the X-API-Key header curl -H "X-API-Key: tmk_your_api_key_here" \ https://your-domain.com/api/tasks

API Key Permissions

API keys can be scoped with granular permissions. Use the resource:action format:

Permission	Description
`*`	Full access to all resources
`tasks:read`	Read tasks and subtasks
`tasks:write`	Create and update tasks
`tasks:delete`	Delete tasks
`companies:read`	Read companies
`projects:read`	Read projects
`folders:read`	Read folders
`goals:read`	Read goals
`tags:read`	Read tags
`tags:write`	Create and update tags
`statuses:read`	Read statuses
`statuses:write`	Create and update statuses
`users:read`	Read users
`users:write`	Create and update users
`agents:read`	Read AI agents
`agents:write`	Create and update agents
`teams:read`	Read teams
`teams:write`	Create and update teams
`assignments:write`	Manage assignments
`templates:read`	Read templates
`views:read`	Read saved views
`analytics:read`	Read analytics data

Entity Hierarchy

TaskFlow uses a structured hierarchy to organize work:

Company └─ Project └─ Folder └─ Goal └─ Task └─ Subtask (recursive)

Each level is optional. Tasks can exist without being assigned to any parent entity, or they can be deeply nested within the full hierarchy.

Tasks API

The core resource for managing work items.

GET/api/tasksList all tasks

POST/api/tasksCreate a new task

GET/api/tasks/:idGet task details

PUT/api/tasks/:idUpdate a task

DELETE/api/tasks/:idDelete a task

GET/api/tasks/archiveList archived tasks

PUT/api/tasks/archiveArchive or unarchive tasks

PUT/api/tasks/reorderReorder a task

Create a task

POST /api/tasks Content-Type: application/json X-API-Key: tmk_your_key { "title": "Review pull request #42", "priority": "high", "status_id": "status-todo", "folder_id": "folder-abc123", "due_date": "2026-03-15", "notes": "Check for security issues" }

Archive tasks

PUT /api/tasks/archive { "task_ids": ["task-abc123", "task-def456"], "action": "archive" }

Reorder a task

PUT /api/tasks/reorder { "task_id": "task-abc123", "sort_order": 2, "folder_id": "folder-xyz", "goal_id": "goal-abc" }

Task object fields

Field	Type	Description
`title`	string	Task name (required)
`notes`	string	Detailed description
`priority`	string	none, low, medium, high
`status_id`	string	Status identifier
`folder_id`	string	Parent folder
`goal_id`	string	Parent goal
`due_date`	string	ISO date (YYYY-MM-DD)
`start_date`	string	ISO date (YYYY-MM-DD)
`parent_task_id`	string	Parent task (for subtasks)
`recurrence_rule`	string	daily, weekly, monthly, yearly

Subtasks

GET/api/tasks/:id/subtasksList subtasks

Subtasks are created via POST /api/tasks with the parent_task_id field set to the parent task's ID. They inherit folder and goal from their parent and can be nested to unlimited depth.

POST /api/tasks { "title": "Review security section", "parent_task_id": "task-abc123" }

Comments & Time Tracking

Comments

GET/api/tasks/:id/commentsList comments

POST/api/tasks/:id/commentsAdd a comment

DELETE/api/tasks/:id/commentsDelete a comment

POST /api/tasks/:id/comments { "content": "Looks good, ready for deploy" }

Time Tracking

GET/api/tasks/:id/timeList time entries

POST/api/tasks/:id/timeStart, stop, or log time

DELETE/api/tasks/:id/timeDelete a time entry

GET/api/time/activeGet currently running timer

// Start a timer POST /api/tasks/:id/time { "action": "start" } // Stop a timer { "action": "stop" } // Log time manually { "action": "manual", "duration_seconds": 3600, "note": "Code review session" }

Attachments

Upload and manage file attachments on tasks.

GET/api/tasks/:id/attachmentsList attachments

POST/api/tasks/:id/attachmentsUpload attachment

DELETE/api/tasks/:id/attachmentsDelete attachment

Uploads use multipart/form-data with a file field. Delete requests send the attachment ID in the body.

# Upload a file curl -X POST \ -H "X-API-Key: tmk_your_key" \ -F "file=@document.pdf" \ https://your-domain.com/api/tasks/task-abc123/attachments

Dependencies

Create blocking relationships between tasks.

GET/api/tasks/:id/dependenciesList dependencies

POST/api/tasks/:id/dependenciesCreate dependency

DELETE/api/tasks/:id/dependenciesRemove dependency

The GET response returns { "blocking": [...], "blocked_by": [...] }. A task cannot depend on itself, and circular dependencies are rejected with a 409 status.

POST /api/tasks/:id/dependencies { "blocking_task_id": "task-abc123", "blocked_task_id": "task-def456" }

Custom Fields

Add arbitrary key-value metadata to tasks.

GET/api/custom-fields?task_id=:idList custom fields for a task

POST/api/custom-fieldsCreate custom field

PUT/api/custom-fieldsUpdate custom field

DELETE/api/custom-fieldsDelete custom field

POST /api/custom-fields { "task_id": "task-abc123", "field_name": "Sprint", "field_value": "2026-Q1" }

Organization API

Manage your workspace hierarchy. All resources support full CRUD operations.

Companies

GET/api/companiesList companies

POST/api/companiesCreate company

PUT/api/companies/:idUpdate company

DELETE/api/companies/:idDelete company

Projects

GET/api/projectsList projects

POST/api/projectsCreate project

GET/api/projects/:idGet project details

PUT/api/projects/:idUpdate project

DELETE/api/projects/:idDelete project

Folders

GET/api/foldersList folders

POST/api/foldersCreate folder

PUT/api/folders/:idUpdate folder

DELETE/api/folders/:idDelete folder

Goals

GET/api/goalsList goals

POST/api/goalsCreate goal

PUT/api/goals/:idUpdate goal

DELETE/api/goals/:idDelete goal

Organization fields

Resource	POST / PUT Fields
`companies`	name, description, color, sort_order
`projects`	name, description, color, company_id, sort_order
`folders`	name, color, company_id, project_id, sort_order
`goals`	name, description, folder_id, color, sort_order, start_date, due_date

Tags & Statuses

Statuses

GET/api/statusesList custom statuses

POST/api/statusesCreate custom status

PUT/api/statuses/:idUpdate status

DELETE/api/statuses/:idDelete status

POST /api/statuses { "name": "In Review", "color": "#a855f7", "is_completed_state": false }

Users

Manage workspace members.

GET/api/usersList users

POST/api/usersCreate user

PUT/api/users/:idUpdate user

DELETE/api/users/:idDelete user

POST /api/users { "name": "Jane Smith", "email": "jane@example.com", "avatar_color": "#3b82f6", "role": "member" }

Both name and email are required. Emails must be unique (returns 409 on conflict). Default role is member.

AI Agents

AI agents are first-class entities in TaskFlow. Each agent can have its own API key, webhook URL, and task assignments.

GET/api/agentsList all agents

POST/api/agentsCreate an agent

GET/api/agents/:idGet agent details

PUT/api/agents/:idUpdate an agent

DELETE/api/agents/:idDelete an agent

Create an AI agent

POST /api/agents Content-Type: application/json { "name": "Code Review Bot", "description": "Automated code reviewer", "avatar_color": "#8b5cf6", "webhook_url": "https://your-server.com/webhook", "webhook_method": "POST", "create_api_key": true }

When create_api_key is set to true, the response will include the raw API key once. Store it securely — it cannot be retrieved again.

API Keys

GET/api/api-keysList API keys (hashes hidden)

POST/api/api-keysCreate a new API key

PUT/api/api-keys/:idUpdate an API key

DELETE/api/api-keys/:idRevoke an API key

Create an API key

POST /api/api-keys { "name": "Production Bot Key", "description": "Key for production bot", "agent_id": "agent-abc123", "permissions": ["tasks:read", "tasks:write"] } // Response includes the raw key (shown only once): { "id": "key-xyz789", "key": "tmk_a1b2c3d4e5f6...", "name": "Production Bot Key" }

Assignments

Assign tasks, folders, goals, or projects to users, teams, or AI agents. Assignments cascade down the hierarchy automatically.

GET/api/assignmentsList assignments

POST/api/assignmentsCreate assignment

DELETE/api/assignmentsRemove assignment

Assign an AI agent to a task

POST /api/assignments { "entity_type": "task", "entity_id": "task-abc123", "assignee_type": "ai_agent", "assignee_id": "agent-xyz789" }

Webhooks

Configure webhook URLs on AI agents to receive real-time notifications when task events occur. TaskFlow will POST event data to your endpoint.

Webhook events

Event	Trigger
`task_created`	A new task is created and assigned to the agent
`task_updated`	An assigned task is modified
`task_completed`	An assigned task is marked as complete
`task_assigned`	The agent is assigned to a task

Webhook payload

// POST to agent's webhook_url { "event": "task_assigned", "timestamp": "2026-03-10T14:30:00Z", "data": { "task_id": "task-abc123", "title": "Review PR #42", "priority": "high", "assignee_id": "agent-xyz789" } }

Webhook delivery history

GET/api/agents/:id/webhooksView delivery history

Each delivery attempt is logged with status code, response body, and timestamp for debugging.

Teams

Teams can contain both human users and AI agents. When a team is assigned to a task, all team members inherit the assignment.

GET/api/teamsList teams

POST/api/teamsCreate team

GET/api/teams/:idGet team details

PUT/api/teams/:idUpdate team

DELETE/api/teams/:idDelete team

GET/api/teams/:id/membersList team members

POST/api/teams/:id/membersAdd team member

DELETE/api/teams/:id/membersRemove team member

POST /api/teams/:id/members { "member_type": "ai_agent", "member_id": "agent-xyz789", "role": "member" }

Templates & Views

Templates

Save task configurations as reusable templates, then instantiate them to create pre-configured tasks.

GET/api/templatesList task templates

POST/api/templatesCreate template

DELETE/api/templates/:idDelete template

POST/api/templates/:id/instantiateCreate task from template

// Create a template POST /api/templates { "name": "Bug Report", "template_data": { "priority": "high", "notes": "Steps to reproduce:" } } // Instantiate POST /api/templates/:id/instantiate { "folder_id": "folder-abc" }

Saved Views

Save filter and display configurations for quick access.

GET/api/viewsList saved views

POST/api/viewsSave a view configuration

PUT/api/views/:idUpdate saved view

DELETE/api/views/:idDelete saved view

POST /api/views { "name": "My High Priority", "view_type": "list", "filters": { "priority": "high" }, "sort_by": "due_date", "sort_dir": "asc" }

Activity & Analytics

Activity Log

Track changes and actions across your workspace.

GET/api/activityList activity log entries

POST/api/activityCreate activity log entry

GET supports limit and offset query parameters for pagination.

POST /api/activity { "entity_type": "task", "entity_id": "task-abc123", "action": "completed", "details": { "by": "agent-xyz" } }

Analytics

Get workspace-wide statistics and trends.

GET/api/analyticsGet workspace analytics

Returns an object with: totalTasks, completedTasks, overdueTasks, dueSoon, completionRate, byPriority, byStatus, trend, goalProgress, and timeThisWeek.

Additional Endpoints

Search

GET/api/search?q=keywordFull-text search across tasks

Additional query parameters: priority, due_before, due_after, completed. Returns up to 50 results.

Bulk Operations

PUT/api/tasks/bulkBulk update tasks

PUT /api/tasks/bulk { "task_ids": ["task-1", "task-2"], "action": "set_priority", "value": "high" } // Actions: complete, uncomplete, delete, // set_priority, move_folder, move_goal

Import / Export

POST/api/importImport tasks from JSON

GET/api/export?format=jsonExport tasks as JSON or CSV

Favorites

GET/api/favoritesList favorites

POST/api/favoritesAdd favorite

DELETE/api/favoritesRemove favorite

POST /api/favorites { "entity_type": "folder", "entity_id": "folder-abc123" }

Notifications

GET/api/notificationsList notifications

POST/api/notificationsManage notifications

POST actions: generate (auto-create overdue/due-soon alerts), mark_all_read, mark_read (with id), clear_all.

Recent Items

GET/api/recentList recently viewed items

POST/api/recentRecord a view

Undo

POST/api/undo-saveSave undo snapshot

POST/api/undoRestore from undo

Undo snapshots expire after 30 seconds. Call /api/undo with { "undo_id": "..." } to restore.

Rate Limiting

API requests are rate-limited per API key. The current limits are generous for normal usage:

100 requests per minute per API key
Browser sessions are not rate-limited
Rate limit headers are included in all responses

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 97 X-RateLimit-Reset: 1709812800