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
| Action | What it does |
|---|---|
| Add comment | Comment on a task, as the connected user. |
| Add label to task | Put a label on a task. |
| Assign task | Assign a task to someone its project is shared with. |
| Complete task | Mark a task done. |
| Create project | Create a project, on its own or inside another one, such as one per client or event. |
| 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. |
| Delete project | Delete a project with its tasks and the projects inside it. |
| Delete task | Delete a task. |
| 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. |
| Get task | Get a task's details, with its comments if you ask for them. |
| List projects | List the projects the connected user can see, with their IDs and parent projects. |
| Update task | Change 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
- Task
tasktextRequired - The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Comment
commenttextRequired - 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
- Task
tasktextRequired - The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Label
labeltextRequired - 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
- Task
tasktextRequired - The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Assignee
assigneetextRequired - 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
- Task
tasktextRequired - 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
- Title
titletextRequired - The project's name.
- Description
descriptiontext - What it's for, as plain text or HTML.
- Parent project
parent_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
- Project
projecttextRequired - The project to add it to.
- Title
titletextRequired - What needs doing.
- Description
descriptiontext - The details, as plain text or HTML.
- Due date
due_datedate and time - When it's due.
- Start date
start_datedate and time - When work on it starts.
- Priority
prioritytext - How urgent it is. Leave blank for none.One of:
low,medium,high,urgent,do_now(DO NOW). - Labels
labelslist - Labels to put on it. A label that doesn't exist yet is made.
- Assignees
assigneeslist - 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
- Project
projecttextRequired - 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
- Task
tasktextRequired - 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
- Project
projecttext - Only this project. Leave blank for every project.
- Done or not
statustext - Which tasks to find.One of:
open(Not done),done,any(Both). Default:open. - Due
duetext - 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_afterdate and time - Only tasks due after this time.
- Due before
due_beforedate and time - Only tasks due before this time.
- Label
labeltext - Only tasks with this label.
- Assignee
assigneetext - Only tasks assigned to this person (their username), or me.
- Priority at least
prioritytext - Only tasks of this priority or higher.One of:
low,medium,high,urgent,do_now(DO NOW). - Words
texttext - Only tasks with these words in their title or description.
- Order
sorttext - 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
limitnumber - 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
- Task
tasktextRequired - The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Include comments
include_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 archived
include_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
- Task
tasktextRequired - The task's ID, the number at the end of its link (…/tasks/42), or the link.
- Title
titletext - A new title. Leave blank to keep it.
- Description
descriptiontext - A new description, plain text or HTML, replacing the old one. Leave blank to keep it.
- Due date
due_datedate and time - A new due date. Leave blank to keep it.
- Start date
start_datedate and time - A new start date. Leave blank to keep it.
- Priority
prioritytext - A new priority. Leave blank to keep it.One of:
low,medium,high,urgent,do_now(DO NOW). - Done
donetext - Mark it done or not done. Leave blank to keep it.One of:
done,not_done(Not done). - Progress
percent_donenumber - How far along it is, in percent from 0 to 100. Leave blank to keep it.From 0 to 100.
- Move to project
projecttext - 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"
}