API Reference/Goals

Goals API

Retrieve goals and their associated tasks. Goals represent high-level objectives that contain related tasks.

List Goals

GET/api/v1/goalsread:goals

Retrieve a paginated list of goals for your team.

Query Parameters

pageintegerPage number (default: 1)

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

statusstringFilter by status: not_started, in_progress, completed, on_hold, cancelled

prioritystringFilter by priority: low, medium, high, critical

owner_iduuidFilter by owner user ID

include_tasksbooleanInclude tasks count (default: false)

sort_bystringSort field (default: created_at)

sort_orderstringSort direction: asc or desc (default: desc)

Request Example

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

Response

{
  "data": [
    {
      "id": "789e0123-e45b-67d8-a901-234567890000",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Q1 Product Launch",
      "description": "Launch the new product features by end of Q1",
      "status": "in_progress",
      "priority": "high",
      "progress": 45,
      "owner_id": "456e7890-e12b-34d5-a678-901234567000",
      "start_date": "2026-10-01",
      "target_date": "2026-12-31",
      "tasks_count": 12,
      "completed_tasks_count": 5,
      "created_at": "2023-12-15T00:00:00Z",
      "updated_at": "2024-01-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 8,
    "has_more": false
  }
}

Get Goal

GET/api/v1/goals/:idread:goals

Retrieve a single goal by ID, optionally including its tasks.

Query Parameters

include_tasksbooleanInclude full task list (default: false)

include_commentsbooleanInclude comments on the goal (default: false)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/goals/789e0123-e45b-67d8-a901-234567890000?include_tasks=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "789e0123-e45b-67d8-a901-234567890000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Q1 Product Launch",
    "description": "Launch the new product features by end of Q1",
    "status": "in_progress",
    "priority": "high",
    "progress": 45,
    "owner_id": "456e7890-e12b-34d5-a678-901234567000",
    "start_date": "2026-10-01",
    "target_date": "2026-12-31",
    "metadata": {},
    "created_at": "2023-12-15T00:00:00Z",
    "updated_at": "2024-01-10T14:30:00Z",
    "tasks": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Implement user authentication",
        "status": "in_progress",
        "priority": "high",
        "assigned_to": "456e7890-e12b-34d5-a678-901234567000"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "title": "Design landing page",
        "status": "completed",
        "priority": "medium",
        "assigned_to": "567e8901-e23b-45d6-a789-012345678000"
      }
    ]
  }
}

Goal Statuses

Goals can have one of the following statuses:

Status	Description
`not_started`	Goal has not been started yet
`in_progress`	Goal is actively being worked on
`on_hold`	Goal is temporarily paused
`completed`	Goal has been achieved
`cancelled`	Goal has been cancelled

Priority Levels

Goals can be assigned one of four priority levels:

Priority	Description
`low`	Nice to have, can be deferred
`medium`	Normal priority, standard timeline
`high`	Important, should be prioritized
`critical`	Urgent, requires immediate attention

Progress Calculation

Goal progress is automatically calculated based on the completion status of its tasks:

progress = (completed_tasks_count / total_tasks_count) * 100

Automatic Updates

Progress is recalculated whenever a task is completed or its status changes. You cannot manually set the progress value.

Tasks API Comments API

Goals API

Retrieve goals and their associated tasks. Goals represent high-level objectives that contain related tasks.

List Goals

GET/api/v1/goalsread:goals

Retrieve a paginated list of goals for your team.

Query Parameters

pageintegerPage number (default: 1)

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

statusstringFilter by status: not_started, in_progress, completed, on_hold, cancelled

prioritystringFilter by priority: low, medium, high, critical

owner_iduuidFilter by owner user ID

include_tasksbooleanInclude tasks count (default: false)

sort_bystringSort field (default: created_at)

sort_orderstringSort direction: asc or desc (default: desc)

Request Example

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

Response

{
  "data": [
    {
      "id": "789e0123-e45b-67d8-a901-234567890000",
      "team_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Q1 Product Launch",
      "description": "Launch the new product features by end of Q1",
      "status": "in_progress",
      "priority": "high",
      "progress": 45,
      "owner_id": "456e7890-e12b-34d5-a678-901234567000",
      "start_date": "2026-10-01",
      "target_date": "2026-12-31",
      "tasks_count": 12,
      "completed_tasks_count": 5,
      "created_at": "2023-12-15T00:00:00Z",
      "updated_at": "2024-01-10T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 8,
    "has_more": false
  }
}

Get Goal

GET/api/v1/goals/:idread:goals

Retrieve a single goal by ID, optionally including its tasks.

Query Parameters

include_tasksbooleanInclude full task list (default: false)

include_commentsbooleanInclude comments on the goal (default: false)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/goals/789e0123-e45b-67d8-a901-234567890000?include_tasks=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": {
    "id": "789e0123-e45b-67d8-a901-234567890000",
    "team_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Q1 Product Launch",
    "description": "Launch the new product features by end of Q1",
    "status": "in_progress",
    "priority": "high",
    "progress": 45,
    "owner_id": "456e7890-e12b-34d5-a678-901234567000",
    "start_date": "2026-10-01",
    "target_date": "2026-12-31",
    "metadata": {},
    "created_at": "2023-12-15T00:00:00Z",
    "updated_at": "2024-01-10T14:30:00Z",
    "tasks": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Implement user authentication",
        "status": "in_progress",
        "priority": "high",
        "assigned_to": "456e7890-e12b-34d5-a678-901234567000"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "title": "Design landing page",
        "status": "completed",
        "priority": "medium",
        "assigned_to": "567e8901-e23b-45d6-a789-012345678000"
      }
    ]
  }
}

Goal Statuses

Goals can have one of the following statuses:

Status	Description
`not_started`	Goal has not been started yet
`in_progress`	Goal is actively being worked on
`on_hold`	Goal is temporarily paused
`completed`	Goal has been achieved
`cancelled`	Goal has been cancelled

Priority Levels

Goals can be assigned one of four priority levels:

Priority	Description
`low`	Nice to have, can be deferred
`medium`	Normal priority, standard timeline
`high`	Important, should be prioritized
`critical`	Urgent, requires immediate attention

Progress Calculation

Goal progress is automatically calculated based on the completion status of its tasks:

progress = (completed_tasks_count / total_tasks_count) * 100

Automatic Updates

Progress is recalculated whenever a task is completed or its status changes. You cannot manually set the progress value.