Vikunja

App · 12 actions

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.

Actions

ActionWhat it does
Add commentComment on a task, as the connected user.
Add label to taskPut a label on a task.
Assign taskAssign a task to someone its project is shared with.
Complete taskMark a task done.
Create projectCreate a project, on its own or inside another one, such as one per client or event.
Create taskAdd 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.
Delete projectDelete a project with its tasks and the projects inside it.
Delete taskDelete a task.
Find tasksFind 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.
Get taskGet a task's details, with its comments if you ask for them.
List projectsList the projects the connected user can see, with their IDs and parent projects.
Update taskChange a task's title, description, due or start date, priority, done, progress or project.

Add comment

Comment on a task, as the connected user.

Inputs

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.
CommentcommenttextRequired
What to write, as plain text or HTML.

Outputs

authortext
The username of who wrote it
author_nametext
The name of who wrote it
commenttext
The comment as plain text
created_attext
When it was written (ISO 8601)
idnumber
The comment's ID
linktext
A link to the comment in Vikunja
task_idnumber
The task's ID
Example output
{
  "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

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.
LabellabeltextRequired
The label's name.

Outputs

assignee_nameslist
The people it's assigned to, as Name (username)
assigneeslist
The usernames of the people it's assigned to
created_attext
When it was created (ISO 8601)
created_bytext
The username of who created it
descriptiontext
Its description as plain text
description_htmltext
Its description as Vikunja saved it, in HTML
donetrue/false
Whether it's done
done_attext
When it was marked done (ISO 8601); empty if not done
due_datetext
When it's due (ISO 8601, UTC); empty if no due date
end_datetext
When it ends (ISO 8601, UTC); empty if none
idnumber
The task's ID, as in its link
label_idslist
Its labels' IDs
labelslist
Its labels' names
linktext
A link to it in Vikunja
percent_donenumber
Its progress, in percent from 0 to 100
prioritynumber
Its priority from 0 (unset) to 5 (DO NOW)
priority_nametext
Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
projecttext
The project it's in
project_idnumber
The project's ID
repeatstrue/false
Whether it repeats when marked done
start_datetext
When it starts (ISO 8601, UTC); empty if none
titletext
Its title
updated_attext
When it last changed (ISO 8601)
Example output
{
  "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

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.
AssigneeassigneetextRequired
Who to assign it to: their username, name or ID, or me.

Outputs

assignee_nameslist
The people it's assigned to, as Name (username)
assigneeslist
The usernames of the people it's assigned to
created_attext
When it was created (ISO 8601)
created_bytext
The username of who created it
descriptiontext
Its description as plain text
description_htmltext
Its description as Vikunja saved it, in HTML
donetrue/false
Whether it's done
done_attext
When it was marked done (ISO 8601); empty if not done
due_datetext
When it's due (ISO 8601, UTC); empty if no due date
end_datetext
When it ends (ISO 8601, UTC); empty if none
idnumber
The task's ID, as in its link
label_idslist
Its labels' IDs
labelslist
Its labels' names
linktext
A link to it in Vikunja
percent_donenumber
Its progress, in percent from 0 to 100
prioritynumber
Its priority from 0 (unset) to 5 (DO NOW)
priority_nametext
Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
projecttext
The project it's in
project_idnumber
The project's ID
repeatstrue/false
Whether it repeats when marked done
start_datetext
When it starts (ISO 8601, UTC); empty if none
titletext
Its title
updated_attext
When it last changed (ISO 8601)
Example output
{
  "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

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.

Outputs

assignee_nameslist
The people it's assigned to, as Name (username)
assigneeslist
The usernames of the people it's assigned to
created_attext
When it was created (ISO 8601)
created_bytext
The username of who created it
descriptiontext
Its description as plain text
description_htmltext
Its description as Vikunja saved it, in HTML
donetrue/false
Whether it's done
done_attext
When it was marked done (ISO 8601); empty if not done
due_datetext
When it's due (ISO 8601, UTC); empty if no due date
end_datetext
When it ends (ISO 8601, UTC); empty if none
idnumber
The task's ID, as in its link
label_idslist
Its labels' IDs
labelslist
Its labels' names
linktext
A link to it in Vikunja
percent_donenumber
Its progress, in percent from 0 to 100
prioritynumber
Its priority from 0 (unset) to 5 (DO NOW)
priority_nametext
Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
projecttext
The project it's in
project_idnumber
The project's ID
repeatstrue/false
Whether it repeats when marked done
start_datetext
When it starts (ISO 8601, UTC); empty if none
titletext
Its title
updated_attext
When it last changed (ISO 8601)
Example output
{
  "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

TitletitletextRequired
The project's name.
Descriptiondescriptiontext
What it's for, as plain text or HTML.
Parent projectparent_projecttext
Put it inside this project. Leave blank for a top-level project.

Outputs

created_attext
When it was created (ISO 8601)
descriptiontext
Its description as plain text
idnumber
The project's ID
identifiertext
Its short identifier, used in task numbers; may be empty
is_archivedtrue/false
Whether it's archived
linktext
A link to it in Vikunja
parent_project_idnumber
Its parent project's ID; 0 if none
pathtext
Its title after its parent projects' titles, such as Office / Finance
titletext
Its title
Example output
{
  "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

ProjectprojecttextRequired
The project to add it to.
TitletitletextRequired
What needs doing.
Descriptiondescriptiontext
The details, as plain text or HTML.
Due datedue_datedate and time
When it's due.
Start datestart_datedate and time
When work on it starts.
Priorityprioritytext
How urgent it is. Leave blank for none.One of: low, medium, high, urgent, do_now (DO NOW).
Labelslabelslist
Labels to put on it. A label that doesn't exist yet is made.
Assigneesassigneeslist
Who will do it: people the project is shared with, by username, or me.

Outputs

assignee_nameslist
The people it's assigned to, as Name (username)
assigneeslist
The usernames of the people it's assigned to
created_attext
When it was created (ISO 8601)
created_bytext
The username of who created it
descriptiontext
Its description as plain text
description_htmltext
Its description as Vikunja saved it, in HTML
donetrue/false
Whether it's done
done_attext
When it was marked done (ISO 8601); empty if not done
due_datetext
When it's due (ISO 8601, UTC); empty if no due date
end_datetext
When it ends (ISO 8601, UTC); empty if none
idnumber
The task's ID, as in its link
label_idslist
Its labels' IDs
labelslist
Its labels' names
linktext
A link to it in Vikunja
percent_donenumber
Its progress, in percent from 0 to 100
prioritynumber
Its priority from 0 (unset) to 5 (DO NOW)
priority_nametext
Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
projecttext
The project it's in
project_idnumber
The project's ID
repeatstrue/false
Whether it repeats when marked done
start_datetext
When it starts (ISO 8601, UTC); empty if none
titletext
Its title
updated_attext
When it last changed (ISO 8601)
Example output
{
  "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

ProjectprojecttextRequired
The project to delete.

Outputs

deletedtrue/false
True once it's deleted
idnumber
The deleted project's ID
titletext
Its title
Example output
{
  "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

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.

Outputs

deletedtrue/false
True once it's deleted
idnumber
The deleted task's ID
project_idnumber
The project it was in
titletext
Its title
Example output
{
  "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

Projectprojecttext
Only this project. Leave blank for every project.
Done or notstatustext
Which tasks to find.One of: open (Not done), done, any (Both). Default: open.
Dueduetext
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 afterdue_afterdate and time
Only tasks due after this time.
Due beforedue_beforedate and time
Only tasks due before this time.
Labellabeltext
Only tasks with this label.
Assigneeassigneetext
Only tasks assigned to this person (their username), or me.
Priority at leastprioritytext
Only tasks of this priority or higher.One of: low, medium, high, urgent, do_now (DO NOW).
Wordstexttext
Only tasks with these words in their title or description.
Ordersorttext
Which come first.One of: due (Soonest due), priority (Highest priority), newest, done (Most recently done), title (Title, A to Z). Default: due.
How manylimitnumber
The most to list. Defaults to 25.From 1 to 200.

Outputs

countnumber
How many tasks were found
has_moretrue/false
Whether more tasks match than were listed
taskslist
The tasks found
Example output
{
  "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

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.
Include commentsinclude_commentstrue/false
Also get its comments, oldest first.

Outputs

assignee_nameslist
The people it's assigned to, as Name (username)
assigneeslist
The usernames of the people it's assigned to
commentslist
Its comments, oldest first, when asked for
created_attext
When it was created (ISO 8601)
created_bytext
The username of who created it
descriptiontext
Its description as plain text
description_htmltext
Its description as Vikunja saved it, in HTML
donetrue/false
Whether it's done
done_attext
When it was marked done (ISO 8601); empty if not done
due_datetext
When it's due (ISO 8601, UTC); empty if no due date
end_datetext
When it ends (ISO 8601, UTC); empty if none
idnumber
The task's ID, as in its link
label_idslist
Its labels' IDs
labelslist
Its labels' names
linktext
A link to it in Vikunja
percent_donenumber
Its progress, in percent from 0 to 100
prioritynumber
Its priority from 0 (unset) to 5 (DO NOW)
priority_nametext
Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
projecttext
The project it's in
project_idnumber
The project's ID
repeatstrue/false
Whether it repeats when marked done
start_datetext
When it starts (ISO 8601, UTC); empty if none
titletext
Its title
updated_attext
When it last changed (ISO 8601)
Example output
{
  "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 archivedinclude_archivedtrue/false
Also list archived projects.

Outputs

countnumber
How many projects there are
projectslist
The projects
Example output
{
  "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

TasktasktextRequired
The task's ID, the number at the end of its link (…/tasks/42), or the link.
Titletitletext
A new title. Leave blank to keep it.
Descriptiondescriptiontext
A new description, plain text or HTML, replacing the old one. Leave blank to keep it.
Due datedue_datedate and time
A new due date. Leave blank to keep it.
Start datestart_datedate and time
A new start date. Leave blank to keep it.
Priorityprioritytext
A new priority. Leave blank to keep it.One of: low, medium, high, urgent, do_now (DO NOW).
Donedonetext
Mark it done or not done. Leave blank to keep it.One of: done, not_done (Not done).
Progresspercent_donenumber
How far along it is, in percent from 0 to 100. Leave blank to keep it.From 0 to 100.
Move to projectprojecttext
Move it to this project. Leave blank to keep it where it is.

Outputs

assignee_nameslist
The people it's assigned to, as Name (username)
assigneeslist
The usernames of the people it's assigned to
created_attext
When it was created (ISO 8601)
created_bytext
The username of who created it
descriptiontext
Its description as plain text
description_htmltext
Its description as Vikunja saved it, in HTML
donetrue/false
Whether it's done
done_attext
When it was marked done (ISO 8601); empty if not done
due_datetext
When it's due (ISO 8601, UTC); empty if no due date
end_datetext
When it ends (ISO 8601, UTC); empty if none
idnumber
The task's ID, as in its link
label_idslist
Its labels' IDs
labelslist
Its labels' names
linktext
A link to it in Vikunja
percent_donenumber
Its progress, in percent from 0 to 100
prioritynumber
Its priority from 0 (unset) to 5 (DO NOW)
priority_nametext
Its priority's name: Unset, Low, Medium, High, Urgent or DO NOW
projecttext
The project it's in
project_idnumber
The project's ID
repeatstrue/false
Whether it repeats when marked done
start_datetext
When it starts (ISO 8601, UTC); empty if none
titletext
Its title
updated_attext
When it last changed (ISO 8601)
Example output
{
  "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"
}

On this page