API Reference/Tasks

Tasks API

Create, read, update, and delete tasks. Tasks belong to goals or can be subtasks of other tasks.

List Tasks

GET/api/v1/tasksread:tasks

Retrieve a paginated list of tasks for your team.

Query Parameters

pageintegerPage number (default: 1)

limitintegerItems per page (default: 50, max: 100)

statusstringFilter by status: to_do, in_progress, completed, on_hold, blocked, in_review

prioritystringFilter by priority: low, medium, high, urgent

assigned_touuidFilter by assignee user ID

goal_iduuidFilter by parent goal ID

parent_task_iduuidFilter by parent task ID (for subtasks)

typestringFilter by type: task, sub_task, bug, story, epic

sort_bystringSort field (default: created_at)

sort_orderstringSort direction: asc or desc (default: desc)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/tasks?status=in_progress&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "goal_id": "789e0123-e45b-67d8-a901-234567890000",
      "title": "Implement user authentication",
      "description": "Add OAuth2 login flow",
      "type": "task",
      "status": "in_progress",
      "priority": "high",
      "assigned_to": "456e7890-e12b-34d5-a678-901234567000",
      "due_date": "2026-12-15",
      "story_points": 5,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-05T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "has_more": true
  }
}

Get Task

GET/api/v1/tasks/:idread:tasks

Retrieve a single task by ID.

Request Example

curl -X GET "https://gateway.thekairos.app/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "goal_id": "789e0123-e45b-67d8-a901-234567890000",
    "title": "Implement user authentication",
    "description": "Add OAuth2 login flow with Google and GitHub providers",
    "type": "task",
    "status": "in_progress",
    "priority": "high",
    "estimated_hours": 8,
    "actual_hours": 4,
    "assigned_to": "456e7890-e12b-34d5-a678-901234567000",
    "created_by": "789e0123-e45b-67d8-a901-234567890000",
    "due_date": "2026-12-15",
    "start_date": "2026-12-01",
    "story_points": 5,
    "metadata": {},
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-05T10:30:00Z"
  }
}

Create Task

POST/api/v1/taskswrite:tasks

Create a new task. Must belong to a goal or be a subtask.

Request Body

titlestringrequiredTask title

descriptionstringTask description

goal_iduuidParent goal ID (required if no parent_task_id)

parent_task_iduuidParent task ID for subtasks

typestringTask type (default: task)

statusstringInitial status (default: to_do)

prioritystringPriority level (default: medium)

assigned_touuidAssignee user ID

due_datedateDue date (ISO 8601)

start_datedateStart date (ISO 8601)

estimated_hoursnumberEstimated hours

story_pointsnumberStory points estimate

metadataobjectCustom metadata

Request Example

curl -X POST "https://gateway.thekairos.app/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user authentication",
    "description": "Add OAuth2 login flow",
    "goal_id": "789e0123-e45b-67d8-a901-234567890000",
    "priority": "high",
    "due_date": "2026-12-15",
    "story_points": 5
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "goal_id": "789e0123-e45b-67d8-a901-234567890000",
    "title": "Implement user authentication",
    "description": "Add OAuth2 login flow",
    "type": "task",
    "status": "to_do",
    "priority": "high",
    "due_date": "2026-12-15",
    "story_points": 5,
    "created_at": "2024-01-10T15:30:00Z",
    "updated_at": "2024-01-10T15:30:00Z"
  }
}

Goal or Parent Task Required

Every task must belong to either a goal (via goal_id) or be a subtask of another task (via parent_task_id). You cannot create orphan tasks.

Update Task

PATCH/api/v1/tasks/:idwrite:tasks

Update an existing task. Only provided fields will be modified.

Request Body

titlestringTask title

descriptionstringTask description

statusstringTask status

prioritystringPriority level

assigned_touuidAssignee user ID (null to unassign)

due_datedateDue date (null to clear)

start_datedateStart date

estimated_hoursnumberEstimated hours

actual_hoursnumberActual hours spent

story_pointsnumberStory points

metadataobjectCustom metadata

Request Example

curl -X PATCH "https://gateway.thekairos.app/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "actual_hours": 6
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Implement user authentication",
    "status": "completed",
    "actual_hours": 6,
    "completed_at": "2024-01-12T14:00:00Z",
    "updated_at": "2024-01-12T14:00:00Z"
  }
}

Delete Task

DELETE/api/v1/tasks/:idwrite:tasks

Permanently delete a task and all its subtasks.

Request Example

curl -X DELETE "https://gateway.thekairos.app/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "deleted": true
  }
}

Cascade Delete

Deleting a task will also delete all of its subtasks. This action cannot be undone.

Task Statuses

Tasks can have one of the following statuses:

Status	Description
`to_do`	Task has not been started
`in_progress`	Task is actively being worked on
`in_review`	Task is complete and awaiting review
`on_hold`	Task is paused
`blocked`	Task cannot proceed due to dependencies
`completed`	Task has been finished
`archived`	Task has been archived

API Overview Goals API

API Reference/Tasks

Tasks API

Create, read, update, and delete tasks. Tasks belong to goals or can be subtasks of other tasks.

List Tasks

GET/api/v1/tasksread:tasks

Retrieve a paginated list of tasks for your team.

Query Parameters

pageintegerPage number (default: 1)

limitintegerItems per page (default: 50, max: 100)

statusstringFilter by status: to_do, in_progress, completed, on_hold, blocked, in_review

prioritystringFilter by priority: low, medium, high, urgent

assigned_touuidFilter by assignee user ID

goal_iduuidFilter by parent goal ID

parent_task_iduuidFilter by parent task ID (for subtasks)

typestringFilter by type: task, sub_task, bug, story, epic

sort_bystringSort field (default: created_at)

sort_orderstringSort direction: asc or desc (default: desc)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/tasks?status=in_progress&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "goal_id": "789e0123-e45b-67d8-a901-234567890000",
      "title": "Implement user authentication",
      "description": "Add OAuth2 login flow",
      "type": "task",
      "status": "in_progress",
      "priority": "high",
      "assigned_to": "456e7890-e12b-34d5-a678-901234567000",
      "due_date": "2026-12-15",
      "story_points": 5,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-05T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "has_more": true
  }
}

Get Task

GET/api/v1/tasks/:idread:tasks

Retrieve a single task by ID.

Request Example

curl -X GET "https://gateway.thekairos.app/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "goal_id": "789e0123-e45b-67d8-a901-234567890000",
    "title": "Implement user authentication",
    "description": "Add OAuth2 login flow with Google and GitHub providers",
    "type": "task",
    "status": "in_progress",
    "priority": "high",
    "estimated_hours": 8,
    "actual_hours": 4,
    "assigned_to": "456e7890-e12b-34d5-a678-901234567000",
    "created_by": "789e0123-e45b-67d8-a901-234567890000",
    "due_date": "2026-12-15",
    "start_date": "2026-12-01",
    "story_points": 5,
    "metadata": {},
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-05T10:30:00Z"
  }
}

Create Task

POST/api/v1/taskswrite:tasks

Create a new task. Must belong to a goal or be a subtask.

Request Body

titlestringrequiredTask title

descriptionstringTask description

goal_iduuidParent goal ID (required if no parent_task_id)

parent_task_iduuidParent task ID for subtasks

typestringTask type (default: task)

statusstringInitial status (default: to_do)

prioritystringPriority level (default: medium)

assigned_touuidAssignee user ID

due_datedateDue date (ISO 8601)

start_datedateStart date (ISO 8601)

estimated_hoursnumberEstimated hours

story_pointsnumberStory points estimate

metadataobjectCustom metadata

Request Example

curl -X POST "https://gateway.thekairos.app/v1/tasks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user authentication",
    "description": "Add OAuth2 login flow",
    "goal_id": "789e0123-e45b-67d8-a901-234567890000",
    "priority": "high",
    "due_date": "2026-12-15",
    "story_points": 5
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "goal_id": "789e0123-e45b-67d8-a901-234567890000",
    "title": "Implement user authentication",
    "description": "Add OAuth2 login flow",
    "type": "task",
    "status": "to_do",
    "priority": "high",
    "due_date": "2026-12-15",
    "story_points": 5,
    "created_at": "2024-01-10T15:30:00Z",
    "updated_at": "2024-01-10T15:30:00Z"
  }
}

Goal or Parent Task Required

Every task must belong to either a goal (via goal_id) or be a subtask of another task (via parent_task_id). You cannot create orphan tasks.

Update Task

PATCH/api/v1/tasks/:idwrite:tasks

Update an existing task. Only provided fields will be modified.

Request Body

titlestringTask title

descriptionstringTask description

statusstringTask status

prioritystringPriority level

assigned_touuidAssignee user ID (null to unassign)

due_datedateDue date (null to clear)

start_datedateStart date

estimated_hoursnumberEstimated hours

actual_hoursnumberActual hours spent

story_pointsnumberStory points

metadataobjectCustom metadata

Request Example

curl -X PATCH "https://gateway.thekairos.app/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "actual_hours": 6
  }'

Response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Implement user authentication",
    "status": "completed",
    "actual_hours": 6,
    "completed_at": "2024-01-12T14:00:00Z",
    "updated_at": "2024-01-12T14:00:00Z"
  }
}

Delete Task

DELETE/api/v1/tasks/:idwrite:tasks

Permanently delete a task and all its subtasks.

Request Example

curl -X DELETE "https://gateway.thekairos.app/v1/tasks/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "deleted": true
  }
}

Cascade Delete

Deleting a task will also delete all of its subtasks. This action cannot be undone.

Task Statuses

Tasks can have one of the following statuses:

Status	Description
`to_do`	Task has not been started
`in_progress`	Task is actively being worked on
`in_review`	Task is complete and awaiting review
`on_hold`	Task is paused
`blocked`	Task cannot proceed due to dependencies
`completed`	Task has been finished
`archived`	Task has been archived

API Overview Goals API