Tasks

Create, list, update, complete, and delete tasks. Link tasks to CRM records, filter by assignee or priority, and track completion stats.

Tasks represent actions to be completed by your team: calls to make, emails to send, meetings to schedule. Each task can be linked to one or more CRM records (contacts, companies, opportunities) and assigned to a workspace user.

List Tasks

GET /api/v1/tasks

Returns a paginated list of tasks matching the given filters.

Query Parameters

Parameter	Type	Default	Description
`mode`	string	--	Preset filter: `all`, `today`, `overdue`, `upcoming`, `completed`
`assigned_to`	string	--	Filter by assignee UUID
`priority`	string	--	Filter by priority: `low`, `medium`, `urgent`
`action_type`	string	--	Filter by type: `call`, `email`, `meeting`, `linkedin_message`, `whatsapp_message`
`linked_entity_id`	string	--	Filter tasks linked to a specific entity
`linked_entity_type`	string	--	Entity type: `contacts`, `companies`, `opportunities`
`filters`	string	--	JSON-encoded FilterGroup for advanced filtering
`sort`	string	--	JSON array for multi-field sorting. When provided, `sort_by` and `sort_dir` are ignored.
`sort_by`	string	`due_date`	Single field to sort by (used only when `sort` is absent or not valid JSON)
`sort_dir`	string	`asc`	Sort direction: `asc` or `desc` (used only with `sort_by`)
`cursor`	string	--	Pagination cursor from a previous response
`limit`	number	`20`	Number of results per page (max 100)

Example

curl -X GET "https://kasar.app/api/v1/tasks?mode=today&assigned_to=550e8400-e29b-41d4-a716-446655440000&limit=20" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json"

Response:

{
  "data": [
    {
      "id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
      "title": "Follow up with Alice about renewal",
      "due_date": "2025-03-15T09:00:00Z",
      "priority": "urgent",
      "action_type": "call",
      "is_completed": false,
      "assigned_to_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2025-03-10T14:22:00Z",
      "updated_at": "2025-03-10T14:22:00Z"
    }
  ],
  "total": 12,
  "nextCursor": "eyJpZCI6IjdhMWIyYzNk..."
}

The list endpoint returns task fields as stored in the database. Many-to-many links (e.g., linked contacts or companies) are not enriched in GET responses. Use linked_entity_id and linked_entity_type query parameters to filter tasks by their links instead. The linked_entities field is an input parameter for POST and PUT only.

Filtering by Mode

The mode parameter applies common preset filters:

Mode	Description
`all`	All tasks regardless of status or date
`today`	Tasks due today that are not completed
`overdue`	Tasks past their due date that are not completed
`upcoming`	Tasks due in the future that are not completed
`completed`	Only completed tasks

Create a Task

POST /api/v1/tasks

Creates a new task and optionally links it to CRM records.

Request Body

Field	Type	Required	Description
`title`	string	Yes	Task title
`due_date`	string	No	ISO 8601 date/time
`priority`	string	No	`low`, `medium`, or `urgent`
`assigned_to_id`	string	No	UUID of the workspace user to assign
`action_type`	string	No	`call`, `email`, `meeting`, `linkedin_message`, `whatsapp_message`
`linked_entities`	array	No	Array of `{ id, type }` objects to link

Example

curl -X POST "https://kasar.app/api/v1/tasks" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Call Alice about contract renewal",
    "due_date": "2025-03-15T09:00:00Z",
    "priority": "urgent",
    "action_type": "call",
    "assigned_to_id": "550e8400-e29b-41d4-a716-446655440000",
    "linked_entities": [
      { "id": "a1b2c3d4-e5f6-7890-abcd-ef0123456789", "type": "contacts" }
    ]
  }'

Response (201):

{
  "task_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "action": "created"
}

When a task is assigned to a user other than the creator, a task_assigned notification is sent automatically to the assignee.

Update a Task

PUT /api/v1/tasks/{id}

Updates one or more fields on an existing task. Only include the fields you want to change.

Request Body

Field	Type	Description
`title`	string	Updated task title
`due_date`	string	Updated due date (ISO 8601)
`priority`	string	`low`, `medium`, or `urgent`
`assigned_to_id`	string	New assignee UUID
`action_type`	string	Updated action type
`linked_entities`	array	Replace linked entities with this list

Example

curl -X PUT "https://kasar.app/api/v1/tasks/7a1b2c3d-4e5f-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "priority": "medium",
    "due_date": "2025-03-20T09:00:00Z"
  }'

Response:

{
  "task_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "action": "updated"
}

Passing linked_entities replaces all existing links. To keep current links, include them in the array alongside any new ones.

Complete or Reopen a Task

PUT /api/v1/tasks/{id}/complete

Marks a task as completed, or reopens a previously completed task.

Request Body

Field	Type	Default	Description
`completed`	boolean	`true`	Set to `false` to reopen a completed task

Example: Complete

curl -X PUT "https://kasar.app/api/v1/tasks/7a1b2c3d-4e5f-6789-abcd-ef0123456789/complete" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{ "completed": true }'

Response:

{
  "task_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "action": "completed"
}

Example: Reopen

curl -X PUT "https://kasar.app/api/v1/tasks/7a1b2c3d-4e5f-6789-abcd-ef0123456789/complete" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{ "completed": false }'

Response:

{
  "task_id": "7a1b2c3d-4e5f-6789-abcd-ef0123456789",
  "action": "reopened"
}

Completing a task automatically sets completed_at to the current timestamp and completed_by to the authenticated user. Reopening clears both fields. A task_completed notification is sent to relevant users.

Delete a Task

DELETE /api/v1/tasks/{id}

Permanently deletes a task and removes all entity links.

Example

curl -X DELETE "https://kasar.app/api/v1/tasks/7a1b2c3d-4e5f-6789-abcd-ef0123456789" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..."

Response:

{
  "deleted": true
}

Task Stats

GET /api/v1/tasks/stats

Returns aggregated task statistics. Each metric is computed with a RBAC-aware SQL COUNT. By default the stats cover all tasks visible to the caller; pass user_id to scope every count to a single assignee.

Query Parameters

Parameter	Type	Default	Description
`user_id`	string	--	Restrict all counts to tasks assigned to this workspace user UUID

Example

curl -X GET "https://kasar.app/api/v1/tasks/stats?user_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..."

Response:

{
  "total": 48,
  "completedToday": 3,
  "remainingToday": 5,
  "overdue": 2,
  "thisWeek": 12,
  "completionRate": 72
}

Field	Description
`total`	Total number of tasks across all statuses
`completedToday`	Completed tasks whose `completed_at` falls today
`remainingToday`	Incomplete tasks due today
`overdue`	Incomplete tasks past their due date
`thisWeek`	Incomplete tasks due in the current week (Monday to Sunday)
`completionRate`	Percentage of completed tasks, `round(completed / total * 100)` (0 to 100; `0` when there are no tasks)

Error Responses

Errors are returned as a flat JSON object: a code, a human-readable message, and — for validation failures — a field_errors array. There is no error wrapper field. Update, complete, and delete return HTTP 400 with this shape on failure.

Task Not Found

{
  "code": "RECORD_NOT_FOUND",
  "message": "Record not found: tasks/7a1b2c3d-4e5f-6789-abcd-ef0123456789"
}

Validation Error

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed: priority: Invalid value for priority",
  "field_errors": [
    { "field": "priority", "message": "Invalid value for priority" }
  ]
}

Tasks

On this page