Tasks

Tasks are project-related action items with due dates and status tracking. They help organize work within projects and can track time spent on completion.

The Task Object

Attributes

Attribute	Type	Description
id	integer	Unique identifier for the task
company_id	integer	ID of the company this task belongs to
user_id	integer	ID of the user who created the task
project_id	integer	ID of the project this task belongs to
title	string	Task title (max 255 characters)
description	string|null	Detailed task description
status	string	Task status: open, in-progress, or done
due	string	Due date in Y-m-d format
planned_hours	number|null	Estimated hours to complete the task
formatted	object	Formatted display data
formatted.relative_due	string	Human-readable relative due date (e.g., "in 2 days")
formatted.due	string	Formatted due date for display
formatted.is_done	boolean	Whether the task is completed
total_time_tracked	string	Total time tracked on this task in HH:MM format
project	object|null	Project object (when included)
created_at	string	ISO 8601 timestamp of creation
updated_at	string	ISO 8601 timestamp of last update

List All Tasks

Returns a paginated list of tasks for a company.

GET /api/companies/{company_id}/tasks

Query Parameters

Parameter	Type	Description
per_page	integer	Number of tasks per page (default: 15)
page	integer	Page number for pagination
filter[status]	string	Filter by status: open, in-progress, or done
include	string	Include related resources (available: project)

Response

{
  "data": [
    {
      "id": 1,
      "company_id": 1,
      "user_id": 1,
      "project_id": 5,
      "title": "Implement user authentication",
      "description": "Set up OAuth2 authentication flow",
      "status": "in-progress",
      "due": "2024-01-31",
      "planned_hours": 8,
      "formatted": {
        "relative_due": "in 5 days",
        "due": "31.01.2024",
        "is_done": false
      },
      "total_time_tracked": "04:30",
      "project": null,
      "created_at": "2024-01-15T10:00:00.000000Z",
      "updated_at": "2024-01-26T14:30:00.000000Z"
    }
  ],
  "links": {
    "first": "https://api.milkee.ch/api/companies/1/tasks?page=1",
    "last": "https://api.milkee.ch/api/companies/1/tasks?page=3",
    "prev": null,
    "next": "https://api.milkee.ch/api/companies/1/tasks?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://api.milkee.ch/api/companies/1/tasks",
    "per_page": 15,
    "to": 15,
    "total": 42
  }
}

Create a Task

Creates a new task within a project.

POST /api/companies/{company_id}/tasks

Request Body

Parameter	Type	Required	Description
title	string	Yes	Task title (max 255 characters)
due	string	Yes	Due date (any valid date format)
project_id	integer	Yes	ID of the project this task belongs to
description	string	No	Detailed task description
status	string	No	Task status: open, in-progress, or done (default: open)
planned_hours	number	No	Estimated hours to complete (min: 0)

Response

Returns the created task object.

{
  "data": {
    "id": 42,
    "company_id": 1,
    "user_id": 1,
    "project_id": 5,
    "title": "Implement user authentication",
    "description": "Set up OAuth2 authentication flow",
    "status": "open",
    "due": "2024-01-31",
    "planned_hours": 8,
    "formatted": {
      "relative_due": "in 5 days",
      "due": "31.01.2024",
      "is_done": false
    },
    "total_time_tracked": "00:00",
    "project": null,
    "created_at": "2024-01-26T10:00:00.000000Z",
    "updated_at": "2024-01-26T10:00:00.000000Z"
  }
}

Retrieve a Task

Retrieves the details of a specific task.

GET /api/companies/{company_id}/tasks/{task_id}

Query Parameters

Parameter	Type	Description
include	string	Include related resources (available: project)

Response

Returns a task object.

{
  "data": {
    "id": 42,
    "company_id": 1,
    "user_id": 1,
    "project_id": 5,
    "title": "Implement user authentication",
    "description": "Set up OAuth2 authentication flow",
    "status": "in-progress",
    "due": "2024-01-31",
    "planned_hours": 8,
    "formatted": {
      "relative_due": "in 5 days",
      "due": "31.01.2024",
      "is_done": false
    },
    "total_time_tracked": "04:30",
    "project": null,
    "created_at": "2024-01-26T10:00:00.000000Z",
    "updated_at": "2024-01-26T14:30:00.000000Z"
  }
}

Update a Task

Updates an existing task.

PUT /api/companies/{company_id}/tasks/{task_id}

Request Body

All parameters are optional. Only include the fields you want to update.

Parameter	Type	Description
title	string	Task title (max 255 characters)
description	string	Detailed task description
status	string	Task status: open, in-progress, or done
due	string	Due date (any valid date format)
project_id	integer	ID of the project this task belongs to
planned_hours	number	Estimated hours to complete (min: 0)

Response

Returns the updated task object.

{
  "data": {
    "id": 42,
    "company_id": 1,
    "user_id": 1,
    "project_id": 5,
    "title": "Implement user authentication",
    "description": "Set up OAuth2 authentication flow with JWT tokens",
    "status": "done",
    "due": "2024-01-31",
    "planned_hours": 10,
    "formatted": {
      "relative_due": "in 5 days",
      "due": "31.01.2024",
      "is_done": true
    },
    "total_time_tracked": "09:45",
    "project": null,
    "created_at": "2024-01-26T10:00:00.000000Z",
    "updated_at": "2024-01-26T16:00:00.000000Z"
  }
}

Delete a Task

Deletes a task permanently.

DELETE /api/companies/{company_id}/tasks/{task_id}

Response

Returns HTTP 204 No Content on success.

Task Statuses

Tasks can have one of three statuses:

• open - Task is created but work hasn't started yet (default status)
• in-progress - Task is currently being worked on
• done - Task has been completed

The status can be updated at any time to reflect the current state of the task.

Time Tracking

Tasks automatically calculate the total time tracked from all associated time track entries. The total_time_tracked field shows the cumulative time in HH:MM format, making it easy to compare against the planned_hours estimate.

Best Practices

Task Planning

Use the planned_hours field to estimate task complexity and workload. This helps with project planning and resource allocation.

Status Workflow

Follow a consistent workflow when updating task statuses. Moving tasks through open → in-progress → done provides clear visibility into work progress.

Due Date Management

Set realistic due dates and use the formatted.relative_due field to prioritize tasks. The system calculates human-readable relative dates to help identify urgent tasks.

Project Association

All tasks must be associated with a project. When moving a task to a different project, ensure the new project belongs to the same company.