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": "2024-01-01",
      "target_date": "2024-03-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": "2024-01-01",
    "target_date": "2024-03-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": "2024-01-01",
      "target_date": "2024-03-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": "2024-01-01",
    "target_date": "2024-03-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.

Core Features

Platforms

Goals API

List Goals

Query Parameters

Request Example

Response

Get Goal

Query Parameters

Request Example

Response

Goal Statuses

Priority Levels

Progress Calculation

Automatic Updates

Core Features

Platforms

Goals API

List Goals

Query Parameters

Request Example

Response

Get Goal

Query Parameters

Request Example

Response

Goal Statuses

Priority Levels

Progress Calculation

Automatic Updates