Tasks

Overview

The Tasks endpoints let you manage tasks and projects within your organization. Tasks can be organized into projects, assigned to users, prioritized, and tracked through customizable statuses.

Base path: /orgs/{orgId}/bot/tasks

List Tasks

Retrieve tasks with optional filtering, sorting, and pagination.

GET /orgs/{orgId}/bot/tasks

Required scope: tasks:read

Query Parameters

Parameter	Type	Default	Description
projectId	UUID	—	Filter by project
teamId	UUID	—	Filter by team
assigneeId	UUID	—	Filter by assignee
statusId	string	—	Filter by status ID
statusCategory	enum	—	Filter by status category: not_started, in_progress, done, cancelled
priority	enum	—	Filter by priority: urgent, high, medium, low, none
dueBefore	ISO 8601	—	Tasks due before this date
dueAfter	ISO 8601	—	Tasks due after this date
parentTaskId	UUID or null	—	Filter subtasks of a parent (null for top-level only)
search	string	—	Full-text search on task title
limit	integer	50	Results per page (1-200)
offset	integer	0	Pagination offset
sort	enum	sort_order	Sort by: created, updated, due, priority, sort_order
sortDir	enum	asc	Sort direction: asc, desc

Example Request

curl -X GET "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks?projectId={projectId}&priority=high&limit=10" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "tasks": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Review Q1 report",
      "description": "Review and approve the Q1 financial report",
      "projectId": "project-uuid",
      "statusId": "in-progress",
      "priority": "high",
      "assigneeId": "user-uuid",
      "dueDate": "2026-04-01T00:00:00.000Z",
      "tags": ["finance", "quarterly"],
      "createdAt": "2026-03-25T10:00:00.000Z",
      "updatedAt": "2026-03-26T14:30:00.000Z"
    }
  ],
  "total": 1
}

Get Task

Retrieve a single task by ID.

GET /orgs/{orgId}/bot/tasks/{taskId}

Required scope: tasks:read

Example Request

curl -X GET "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks/{taskId}" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Review Q1 report",
  "description": "Review and approve the Q1 financial report",
  "projectId": "project-uuid",
  "statusId": "in-progress",
  "priority": "high",
  "assigneeId": "user-uuid",
  "dueDate": "2026-04-01T00:00:00.000Z",
  "startDate": null,
  "estimate": 4,
  "tags": ["finance", "quarterly"],
  "parentTaskId": null,
  "sprintId": null,
  "customFields": {},
  "createdAt": "2026-03-25T10:00:00.000Z",
  "updatedAt": "2026-03-26T14:30:00.000Z"
}

Error: Task Not Found

{
  "error": "Task not found"
}

Create Task

Create a new task.

POST /orgs/{orgId}/bot/tasks

Required scope: tasks:write

Request Body

Field	Type	Required	Description
title	string (1-500)	Yes	Task title
description	string (max 10,000)	No	Task description
projectId	UUID	No	Project to add the task to
statusId	string (max 50)	No	Status ID (uses project default if omitted)
priority	enum	No	urgent, high, medium, low, none
assigneeId	UUID	No	User to assign the task to
dueDate	ISO 8601	No	Due date
startDate	ISO 8601	No	Start date
parentTaskId	UUID	No	Parent task (creates a subtask)
estimate	number (0-1000)	No	Time estimate in hours
tags	string[] (max 20)	No	Tags (each max 50 chars)
sprintId	UUID	No	Sprint to add the task to
customFields	object	No	Key-value pairs for custom fields
sourceType	enum	No	Origin: message, call, email, pa, manual, recurring
sourceId	string	No	ID of the source resource
sourceUrl	URL	No	URL linking back to the source

Example Request

curl -X POST "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks" \
  -H "Authorization: Bearer mak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy new feature",
    "description": "Deploy the authentication refactor to production",
    "projectId": "project-uuid",
    "priority": "high",
    "assigneeId": "user-uuid",
    "dueDate": "2026-04-05T00:00:00.000Z",
    "tags": ["deployment", "auth"]
  }'

Example Response

{
  "id": "new-task-uuid",
  "title": "Deploy new feature",
  "description": "Deploy the authentication refactor to production",
  "projectId": "project-uuid",
  "priority": "high",
  "assigneeId": "user-uuid",
  "dueDate": "2026-04-05T00:00:00.000Z",
  "createdAt": "2026-03-27T12:00:00.000Z"
}

Returns 201 Created on success.

Update Task

Update an existing task. Only include the fields you want to change.

PATCH /orgs/{orgId}/bot/tasks/{taskId}

Required scope: tasks:write

Request Body

Field	Type	Description
title	string (1-500)	New title
description	string or null	New description (null to clear)
statusId	string (max 50)	New status ID
priority	enum	New priority
assigneeId	UUID or null	New assignee (null to unassign)
dueDate	ISO 8601 or null	New due date (null to clear)
startDate	ISO 8601 or null	New start date (null to clear)
estimate	number or null	New estimate (null to clear)
tags	string[]	Replace all tags
sortOrder	number	Position in the list
sprintId	UUID or null	Move to sprint (null to remove)
customFields	object	Update custom fields

Example Request

curl -X PATCH "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks/{taskId}" \
  -H "Authorization: Bearer mak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "urgent",
    "dueDate": "2026-04-01T00:00:00.000Z"
  }'

Example Response

Returns the full updated task object.

Delete Task

Permanently delete a task.

DELETE /orgs/{orgId}/bot/tasks/{taskId}

Required scope: tasks:write

Example Request

curl -X DELETE "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks/{taskId}" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "message": "Task deleted"
}

List Projects

Retrieve all projects, optionally filtered by team.

GET /orgs/{orgId}/bot/tasks/projects

Required scope: tasks:read

Query Parameters

Parameter	Type	Description
teamId	UUID	Filter projects by team

Example Request

curl -X GET "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks/projects?teamId={teamId}" \
  -H "Authorization: Bearer mak_..."

Example Response

{
  "projects": [
    {
      "id": "project-uuid",
      "name": "Q1 Planning",
      "description": "Q1 2026 planning and tracking",
      "icon": "clipboard",
      "color": "#4F46E5",
      "isPrivate": false,
      "createdAt": "2026-01-15T08:00:00.000Z"
    }
  ]
}

Create Project

Create a new task project.

POST /orgs/{orgId}/bot/tasks/projects

Required scope: tasks:write

Request Body

Field	Type	Required	Description
name	string (1-100)	Yes	Project name
description	string (max 2,000)	No	Project description
icon	string (max 50)	No	Icon identifier
color	hex color	No	Project color (e.g., #4F46E5)
isPrivate	boolean	No	Whether the project is private

Example Request

curl -X POST "https://app.mandraki.cloud/api/v1/orgs/{orgId}/bot/tasks/projects" \
  -H "Authorization: Bearer mak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release v2.0",
    "description": "Track all tasks for the v2.0 release",
    "color": "#059669"
  }'

Example Response

Returns 201 Created with the created project object.