# Vikunja

> Run your to-do lists in Vikunja: create, update, complete, label, assign and find tasks, comment, manage projects, and start a workflow when a task is created or done.

App · 12 actions. Web page: https://docs.lodol.com/docs/integrations/vikunja

## Actions

### Add comment

Comment on a task, as the connected user.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Comment (`comment`, text, required): What to write, as plain text or HTML.

**Outputs**

- `author` (text): The username of who wrote it
- `author_name` (text): The name of who wrote it
- `comment` (text): The comment as plain text
- `created_at` (text): When it was written (ISO 8601)
- `id` (number): The comment's ID
- `link` (text): A link to the comment in Vikunja
- `task_id` (number): The task's ID

**Example output**

```json
{
  "author": "alice",
  "author_name": "Alice Example",
  "comment": "Paid by card, receipt in the shared folder.",
  "created_at": "2026-11-06T09:12:00Z",
  "id": 7,
  "link": "https://app.vikunja.cloud/tasks/42#comment-7",
  "task_id": 42
}
```

### Add label to task

Put a label on a task. A label that doesn't exist yet is made; one already on the task is left as it is.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Label (`label`, text, required): The label's name.

**Outputs**

- `assignee_names` (list): The people it's assigned to, as Name (username)
- `assignees` (list): The usernames of the people it's assigned to
- `created_at` (text): When it was created (ISO 8601)
- `created_by` (text): The username of who created it
- `description` (text): Its description as plain text
- `description_html` (text): Its description as Vikunja saved it, in HTML
- `done` (true/false): Whether it's done
- `done_at` (text): When it was marked done (ISO 8601); empty if not done
- `due_date` (text): When it's due (ISO 8601, UTC); empty if no due date
- `end_date` (text): When it ends (ISO 8601, UTC); empty if none
- `id` (number): The task's ID, as in its link
- `label_ids` (list): Its labels' IDs
- `labels` (list): Its labels' names
- `link` (text): A link to it in Vikunja
- `percent_done` (number): Its progress, in percent from 0 to 100
- `priority` (number): Its priority from 0 (unset) to 5 (DO NOW)
- `priority_name` (text): Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
- `project` (text): The project it's in
- `project_id` (number): The project's ID
- `repeats` (true/false): Whether it repeats when marked done
- `start_date` (text): When it starts (ISO 8601, UTC); empty if none
- `title` (text): Its title
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "assignee_names": [
    "Bob Builder (bob)"
  ],
  "assignees": [
    "bob"
  ],
  "created_at": "2026-11-05T19:34:22Z",
  "created_by": "alice",
  "description": "The bill came by email on Monday.",
  "description_html": "<p>The bill came by email on Monday.</p>",
  "done": false,
  "done_at": "",
  "due_date": "2026-11-10T17:00:00Z",
  "end_date": "",
  "id": 42,
  "label_ids": [
    3,
    1
  ],
  "labels": [
    "Finance",
    "Urgent"
  ],
  "link": "https://app.vikunja.cloud/tasks/42",
  "percent_done": 0,
  "priority": 3,
  "priority_name": "High",
  "project": "Office",
  "project_id": 3,
  "repeats": false,
  "start_date": "",
  "title": "Pay the electricity bill",
  "updated_at": "2026-11-05T19:34:22Z"
}
```

### Assign task

Assign a task to someone its project is shared with. Anyone already assigned stays assigned.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Assignee (`assignee`, text, required): Who to assign it to: their username, name or ID, or me.

**Outputs**

- `assignee_names` (list): The people it's assigned to, as Name (username)
- `assignees` (list): The usernames of the people it's assigned to
- `created_at` (text): When it was created (ISO 8601)
- `created_by` (text): The username of who created it
- `description` (text): Its description as plain text
- `description_html` (text): Its description as Vikunja saved it, in HTML
- `done` (true/false): Whether it's done
- `done_at` (text): When it was marked done (ISO 8601); empty if not done
- `due_date` (text): When it's due (ISO 8601, UTC); empty if no due date
- `end_date` (text): When it ends (ISO 8601, UTC); empty if none
- `id` (number): The task's ID, as in its link
- `label_ids` (list): Its labels' IDs
- `labels` (list): Its labels' names
- `link` (text): A link to it in Vikunja
- `percent_done` (number): Its progress, in percent from 0 to 100
- `priority` (number): Its priority from 0 (unset) to 5 (DO NOW)
- `priority_name` (text): Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
- `project` (text): The project it's in
- `project_id` (number): The project's ID
- `repeats` (true/false): Whether it repeats when marked done
- `start_date` (text): When it starts (ISO 8601, UTC); empty if none
- `title` (text): Its title
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "assignee_names": [
    "Bob Builder (bob)"
  ],
  "assignees": [
    "bob"
  ],
  "created_at": "2026-11-05T19:34:22Z",
  "created_by": "alice",
  "description": "The bill came by email on Monday.",
  "description_html": "<p>The bill came by email on Monday.</p>",
  "done": false,
  "done_at": "",
  "due_date": "2026-11-10T17:00:00Z",
  "end_date": "",
  "id": 42,
  "label_ids": [
    3,
    1
  ],
  "labels": [
    "Finance",
    "Urgent"
  ],
  "link": "https://app.vikunja.cloud/tasks/42",
  "percent_done": 0,
  "priority": 3,
  "priority_name": "High",
  "project": "Office",
  "project_id": 3,
  "repeats": false,
  "start_date": "",
  "title": "Pay the electricity bill",
  "updated_at": "2026-11-05T19:34:22Z"
}
```

### Complete task

Mark a task done. A repeating task moves on to its next date instead and stays open, as in Vikunja.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.

**Outputs**

- `assignee_names` (list): The people it's assigned to, as Name (username)
- `assignees` (list): The usernames of the people it's assigned to
- `created_at` (text): When it was created (ISO 8601)
- `created_by` (text): The username of who created it
- `description` (text): Its description as plain text
- `description_html` (text): Its description as Vikunja saved it, in HTML
- `done` (true/false): Whether it's done
- `done_at` (text): When it was marked done (ISO 8601); empty if not done
- `due_date` (text): When it's due (ISO 8601, UTC); empty if no due date
- `end_date` (text): When it ends (ISO 8601, UTC); empty if none
- `id` (number): The task's ID, as in its link
- `label_ids` (list): Its labels' IDs
- `labels` (list): Its labels' names
- `link` (text): A link to it in Vikunja
- `percent_done` (number): Its progress, in percent from 0 to 100
- `priority` (number): Its priority from 0 (unset) to 5 (DO NOW)
- `priority_name` (text): Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
- `project` (text): The project it's in
- `project_id` (number): The project's ID
- `repeats` (true/false): Whether it repeats when marked done
- `start_date` (text): When it starts (ISO 8601, UTC); empty if none
- `title` (text): Its title
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "assignee_names": [
    "Bob Builder (bob)"
  ],
  "assignees": [
    "bob"
  ],
  "created_at": "2026-11-05T19:34:22Z",
  "created_by": "alice",
  "description": "The bill came by email on Monday.",
  "description_html": "<p>The bill came by email on Monday.</p>",
  "done": false,
  "done_at": "",
  "due_date": "2026-11-10T17:00:00Z",
  "end_date": "",
  "id": 42,
  "label_ids": [
    3,
    1
  ],
  "labels": [
    "Finance",
    "Urgent"
  ],
  "link": "https://app.vikunja.cloud/tasks/42",
  "percent_done": 0,
  "priority": 3,
  "priority_name": "High",
  "project": "Office",
  "project_id": 3,
  "repeats": false,
  "start_date": "",
  "title": "Pay the electricity bill",
  "updated_at": "2026-11-05T19:34:22Z"
}
```

### Create project

Create a project, on its own or inside another one, such as one per client or event.

**Inputs**

- Title (`title`, text, required): The project's name.
- Description (`description`, text): What it's for, as plain text or HTML.
- Parent project (`parent_project`, text): Put it inside this project. Leave blank for a top-level project.

**Outputs**

- `created_at` (text): When it was created (ISO 8601)
- `description` (text): Its description as plain text
- `id` (number): The project's ID
- `identifier` (text): Its short identifier, used in task numbers; may be empty
- `is_archived` (true/false): Whether it's archived
- `link` (text): A link to it in Vikunja
- `parent_project_id` (number): Its parent project's ID; 0 if none
- `path` (text): Its title after its parent projects' titles, such as Office / Finance
- `title` (text): Its title

**Example output**

```json
{
  "created_at": "2026-11-05T19:34:22Z",
  "description": "Office jobs, shared with Bob.",
  "id": 3,
  "identifier": "OFF",
  "is_archived": false,
  "link": "https://app.vikunja.cloud/projects/3",
  "parent_project_id": 0,
  "path": "Office",
  "title": "Office"
}
```

### Create task

Add a task to a project, such as one from an email, a form or a chat message, with a due date, priority, labels, assignees and a description.

**Inputs**

- Project (`project`, text, required): The project to add it to.
- Title (`title`, text, required): What needs doing.
- Description (`description`, text): The details, as plain text or HTML.
- Due date (`due_date`, date and time): When it's due.
- Start date (`start_date`, date and time): When work on it starts.
- Priority (`priority`, text): How urgent it is. Leave blank for none. One of: `low`, `medium`, `high`, `urgent`, `do_now` (DO NOW).
- Labels (`labels`, list): Labels to put on it. A label that doesn't exist yet is made.
- Assignees (`assignees`, list): Who will do it: people the project is shared with, by username, or me.

**Outputs**

- `assignee_names` (list): The people it's assigned to, as Name (username)
- `assignees` (list): The usernames of the people it's assigned to
- `created_at` (text): When it was created (ISO 8601)
- `created_by` (text): The username of who created it
- `description` (text): Its description as plain text
- `description_html` (text): Its description as Vikunja saved it, in HTML
- `done` (true/false): Whether it's done
- `done_at` (text): When it was marked done (ISO 8601); empty if not done
- `due_date` (text): When it's due (ISO 8601, UTC); empty if no due date
- `end_date` (text): When it ends (ISO 8601, UTC); empty if none
- `id` (number): The task's ID, as in its link
- `label_ids` (list): Its labels' IDs
- `labels` (list): Its labels' names
- `link` (text): A link to it in Vikunja
- `percent_done` (number): Its progress, in percent from 0 to 100
- `priority` (number): Its priority from 0 (unset) to 5 (DO NOW)
- `priority_name` (text): Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
- `project` (text): The project it's in
- `project_id` (number): The project's ID
- `repeats` (true/false): Whether it repeats when marked done
- `start_date` (text): When it starts (ISO 8601, UTC); empty if none
- `title` (text): Its title
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "assignee_names": [
    "Bob Builder (bob)"
  ],
  "assignees": [
    "bob"
  ],
  "created_at": "2026-11-05T19:34:22Z",
  "created_by": "alice",
  "description": "The bill came by email on Monday.",
  "description_html": "<p>The bill came by email on Monday.</p>",
  "done": false,
  "done_at": "",
  "due_date": "2026-11-10T17:00:00Z",
  "end_date": "",
  "id": 42,
  "label_ids": [
    3,
    1
  ],
  "labels": [
    "Finance",
    "Urgent"
  ],
  "link": "https://app.vikunja.cloud/tasks/42",
  "percent_done": 0,
  "priority": 3,
  "priority_name": "High",
  "project": "Office",
  "project_id": 3,
  "repeats": false,
  "start_date": "",
  "title": "Pay the electricity bill",
  "updated_at": "2026-11-05T19:34:22Z"
}
```

### Delete project

Delete a project with its tasks and the projects inside it. On a server with a Trash, such as Vikunja Cloud, it can be restored from there for 30 days.

**Inputs**

- Project (`project`, text, required): The project to delete.

**Outputs**

- `deleted` (true/false): True once it's deleted
- `id` (number): The deleted project's ID
- `title` (text): Its title

**Example output**

```json
{
  "deleted": true,
  "id": 7,
  "title": "Old client"
}
```

### Delete task

Delete a task. On a server with a Trash, such as Vikunja Cloud, it can be restored from there for 30 days.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.

**Outputs**

- `deleted` (true/false): True once it's deleted
- `id` (number): The deleted task's ID
- `project_id` (number): The project it was in
- `title` (text): Its title

**Example output**

```json
{
  "deleted": true,
  "id": 42,
  "project_id": 3,
  "title": "Pay the electricity bill"
}
```

### Find tasks

Find tasks by project, done or not, when they're due (overdue, today, in the next 7 days or between dates), label, assignee, priority or words. Soonest due first, unless you pick another order.

**Inputs**

- Project (`project`, text): Only this project. Leave blank for every project.
- Done or not (`status`, text): Which tasks to find. One of: `open` (Not done), `done`, `any` (Both). Default: `open`.
- Due (`due`, text): Only tasks due then. Today and the next 7 days follow the time zone in the user's Vikunja settings. One of: `any` (Any time, or no due date), `overdue`, `today`, `next_7_days` (Today or in the next 6 days). Default: `any`.
- Due after (`due_after`, date and time): Only tasks due after this time.
- Due before (`due_before`, date and time): Only tasks due before this time.
- Label (`label`, text): Only tasks with this label.
- Assignee (`assignee`, text): Only tasks assigned to this person (their username), or me.
- Priority at least (`priority`, text): Only tasks of this priority or higher. One of: `low`, `medium`, `high`, `urgent`, `do_now` (DO NOW).
- Words (`text`, text): Only tasks with these words in their title or description.
- Order (`sort`, text): Which come first. One of: `due` (Soonest due), `priority` (Highest priority), `newest`, `done` (Most recently done), `title` (Title, A to Z). Default: `due`.
- How many (`limit`, number): The most to list. Defaults to 25. From 1 to 200.

**Outputs**

- `count` (number): How many tasks were found
- `has_more` (true/false): Whether more tasks match than were listed
- `tasks` (list): The tasks found

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "tasks": [
    {
      "assignee_names": [
        "Bob Builder (bob)"
      ],
      "assignees": [
        "bob"
      ],
      "created_at": "2026-11-05T19:34:22Z",
      "created_by": "alice",
      "description": "The bill came by email on Monday.",
      "description_html": "<p>The bill came by email on Monday.</p>",
      "done": false,
      "done_at": "",
      "due_date": "2026-11-10T17:00:00Z",
      "end_date": "",
      "id": 42,
      "label_ids": [
        3,
        1
      ],
      "labels": [
        "Finance",
        "Urgent"
      ],
      "link": "https://app.vikunja.cloud/tasks/42",
      "percent_done": 0,
      "priority": 3,
      "priority_name": "High",
      "project": "Office",
      "project_id": 3,
      "repeats": false,
      "start_date": "",
      "title": "Pay the electricity bill",
      "updated_at": "2026-11-05T19:34:22Z"
    }
  ]
}
```

### Get task

Get a task's details, with its comments if you ask for them.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Include comments (`include_comments`, true/false): Also get its comments, oldest first.

**Outputs**

- `assignee_names` (list): The people it's assigned to, as Name (username)
- `assignees` (list): The usernames of the people it's assigned to
- `comments` (list): Its comments, oldest first, when asked for
- `created_at` (text): When it was created (ISO 8601)
- `created_by` (text): The username of who created it
- `description` (text): Its description as plain text
- `description_html` (text): Its description as Vikunja saved it, in HTML
- `done` (true/false): Whether it's done
- `done_at` (text): When it was marked done (ISO 8601); empty if not done
- `due_date` (text): When it's due (ISO 8601, UTC); empty if no due date
- `end_date` (text): When it ends (ISO 8601, UTC); empty if none
- `id` (number): The task's ID, as in its link
- `label_ids` (list): Its labels' IDs
- `labels` (list): Its labels' names
- `link` (text): A link to it in Vikunja
- `percent_done` (number): Its progress, in percent from 0 to 100
- `priority` (number): Its priority from 0 (unset) to 5 (DO NOW)
- `priority_name` (text): Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
- `project` (text): The project it's in
- `project_id` (number): The project's ID
- `repeats` (true/false): Whether it repeats when marked done
- `start_date` (text): When it starts (ISO 8601, UTC); empty if none
- `title` (text): Its title
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "assignee_names": [
    "Bob Builder (bob)"
  ],
  "assignees": [
    "bob"
  ],
  "comments": [
    {
      "author": "alice",
      "author_name": "Alice Example",
      "comment": "Paid by card, receipt in the shared folder.",
      "created_at": "2026-11-06T09:12:00Z",
      "id": 7
    }
  ],
  "created_at": "2026-11-05T19:34:22Z",
  "created_by": "alice",
  "description": "The bill came by email on Monday.",
  "description_html": "<p>The bill came by email on Monday.</p>",
  "done": false,
  "done_at": "",
  "due_date": "2026-11-10T17:00:00Z",
  "end_date": "",
  "id": 42,
  "label_ids": [
    3,
    1
  ],
  "labels": [
    "Finance",
    "Urgent"
  ],
  "link": "https://app.vikunja.cloud/tasks/42",
  "percent_done": 0,
  "priority": 3,
  "priority_name": "High",
  "project": "Office",
  "project_id": 3,
  "repeats": false,
  "start_date": "",
  "title": "Pay the electricity bill",
  "updated_at": "2026-11-05T19:34:22Z"
}
```

### List projects

List the projects the connected user can see, with their IDs and parent projects.

**Inputs**

- Include archived (`include_archived`, true/false): Also list archived projects.

**Outputs**

- `count` (number): How many projects there are
- `projects` (list): The projects

**Example output**

```json
{
  "count": 1,
  "projects": [
    {
      "created_at": "2026-11-05T19:34:22Z",
      "description": "Office jobs, shared with Bob.",
      "id": 3,
      "identifier": "OFF",
      "is_archived": false,
      "link": "https://app.vikunja.cloud/projects/3",
      "parent_project_id": 0,
      "path": "Office",
      "title": "Office"
    }
  ]
}
```

### Update task

Change a task's title, description, due or start date, priority, done, progress or project. Only the fields you fill in change.

**Inputs**

- Task (`task`, text, required): The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Title (`title`, text): A new title. Leave blank to keep it.
- Description (`description`, text): A new description, plain text or HTML, replacing the old one. Leave blank to keep it.
- Due date (`due_date`, date and time): A new due date. Leave blank to keep it.
- Start date (`start_date`, date and time): A new start date. Leave blank to keep it.
- Priority (`priority`, text): A new priority. Leave blank to keep it. One of: `low`, `medium`, `high`, `urgent`, `do_now` (DO NOW).
- Done (`done`, text): Mark it done or not done. Leave blank to keep it. One of: `done`, `not_done` (Not done).
- Progress (`percent_done`, number): How far along it is, in percent from 0 to 100. Leave blank to keep it. From 0 to 100.
- Move to project (`project`, text): Move it to this project. Leave blank to keep it where it is.

**Outputs**

- `assignee_names` (list): The people it's assigned to, as Name (username)
- `assignees` (list): The usernames of the people it's assigned to
- `created_at` (text): When it was created (ISO 8601)
- `created_by` (text): The username of who created it
- `description` (text): Its description as plain text
- `description_html` (text): Its description as Vikunja saved it, in HTML
- `done` (true/false): Whether it's done
- `done_at` (text): When it was marked done (ISO 8601); empty if not done
- `due_date` (text): When it's due (ISO 8601, UTC); empty if no due date
- `end_date` (text): When it ends (ISO 8601, UTC); empty if none
- `id` (number): The task's ID, as in its link
- `label_ids` (list): Its labels' IDs
- `labels` (list): Its labels' names
- `link` (text): A link to it in Vikunja
- `percent_done` (number): Its progress, in percent from 0 to 100
- `priority` (number): Its priority from 0 (unset) to 5 (DO NOW)
- `priority_name` (text): Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
- `project` (text): The project it's in
- `project_id` (number): The project's ID
- `repeats` (true/false): Whether it repeats when marked done
- `start_date` (text): When it starts (ISO 8601, UTC); empty if none
- `title` (text): Its title
- `updated_at` (text): When it last changed (ISO 8601)

**Example output**

```json
{
  "assignee_names": [
    "Bob Builder (bob)"
  ],
  "assignees": [
    "bob"
  ],
  "created_at": "2026-11-05T19:34:22Z",
  "created_by": "alice",
  "description": "The bill came by email on Monday.",
  "description_html": "<p>The bill came by email on Monday.</p>",
  "done": false,
  "done_at": "",
  "due_date": "2026-11-10T17:00:00Z",
  "end_date": "",
  "id": 42,
  "label_ids": [
    3,
    1
  ],
  "labels": [
    "Finance",
    "Urgent"
  ],
  "link": "https://app.vikunja.cloud/tasks/42",
  "percent_done": 0,
  "priority": 3,
  "priority_name": "High",
  "project": "Office",
  "project_id": 3,
  "repeats": false,
  "start_date": "",
  "title": "Pay the electricity bill",
  "updated_at": "2026-11-05T19:34:22Z"
}
```
