Vikunja

Vikunja Skill

Connects an OpenClaw agent to any Vikunja instance via its REST API (/api/v1). Uses an API token for authentication — no session management needed.

Configuration (required env vars)

The agent must confirm both vars are set before making any request. If missing, tell the user exactly which var is absent and where to create the token (Settings → API Tokens in the Vikunja web UI).

Important API conventions

Vikunja uses non-standard HTTP verbs:

• PUT = create a new resource
• POST = update an existing resource
• GET = read / list
• DELETE = delete

All requests:

• Header: Authorization: Bearer <VIKUNJA_API_TOKEN>
• Header: Content-Type: application/json
• Base: ${VIKUNJA_BASE_URL}/api/v1

Paginated list endpoints accept ?page=N&per_page=50&s=<search>. Response headers x-pagination-total-pages and x-pagination-result-count tell you if more pages exist.

Supported operations

See references/endpoints.md for the full endpoint reference.

Projects

• List all projects the user has access to
• Create a new project
• Get a single project by ID

Tasks

• List tasks (all, or filtered by project)
• Get a single task by ID
• Create a task in a project
• Update a task (title, description, priority, due date, percent done)
• Mark a task as done ("done": true)
• Delete a task

Labels

• List all available labels
• Create a label
• Add a label to a task
• Remove a label from a task

Assignees

• Add a user as assignee to a task
• Remove an assignee from a task
• List task assignees

Reminders

• Add a reminder to a task (absolute datetime or relative offset)
• Remove a reminder from a task
• Reminders are part of the task object — use the task update flow

Task Relations

• Create a relation between two tasks (precedes, follows, blocked_by, subtask, etc.)
• Delete a relation
• When creating a new task with a known relation, use related_tasks inline in the body — no separate call needed
• When adding relations to already-existing tasks, use PUT /tasks/{id}/relations

Workflow guidelines

1. Resolve names to IDs first. If the user says "add a task to my Work project", list projects and find the ID for "Work" before creating the task.
2. Confirm destructive actions. Before deleting a task or project, confirm with the user.
3. Show structured output. When listing tasks, present title, due date, priority, labels, and done status. Format dates in a human-readable way.
4. Handle pagination. If x-pagination-total-pages > 1, fetch subsequent pages or inform the user that results are truncated.
5. Error handling. On HTTP 4xx/5xx, surface the message field from the JSON response to the user. On 401, remind them to check VIKUNJA_API_TOKEN.

Smart task creation

When the user asks to create a task, follow this enrichment workflow before making any write requests.

Step 1 — Gather context (parallel where possible)

• Resolve project name → ID (GET /projects if needed)
• GET /projects/{projectID}/tasks?per_page=50 — fetch existing tasks so you can spot related work, naming conventions, and priority patterns
• GET /labels?per_page=50 — fetch available labels so you can suggest matching ones

Step 2 — Infer task fields

Using the user's request and the context collected above, reason about:

Simplicity rule: If the request is a single, unambiguous action with no implied context (e.g. "add a task called 'Buy milk'"), skip enrichment entirely and create the task with just the title. Do not over-engineer simple requests.

Step 3 — Confirm if enriched

If you inferred any of the following beyond the raw title, present a structured proposal and ask the user to confirm or adjust before creating:

• a non-empty description
• a priority > 0
• one or more labels
• a due date or start date
• any relations

Present the proposal in this format:

**New task proposal**
Title: <title>
Project: <project name>
Priority: <level or none>
Start: <date or none>
Due: <date or none>
Labels: <list or none>
Relations: <list or none>
Description:
<description or none>

Shall I create it as above, or would you like to change anything?

Date rules:

• If the user gives an explicit date → parse and include it, no need to ask.
• If the user uses vague time language ("soon", "eventually") → ask for a concrete date rather than guessing. Do not silently skip if context strongly implies urgency.
• If no date is mentioned and context doesn't call for one → omit both fields.

If the user confirms (or the task is simple and no confirmation is needed), proceed to Step 4.

Step 4 — Create and apply

1. PUT /projects/{projectID}/tasks — with title, description, priority, due_date, and related_tasks inline (for relations to existing tasks)
2. For each confirmed label: PUT /tasks/{newTaskID}/labels with {"label_id": N}
3. Report back: task title, its assigned ID/index, and a link if possible.

Labels cannot be set during creation — they must be applied via separate PUT /tasks/{id}/labels calls after the task is created.

Safe task update — mandatory pattern

Vikunja's POST /tasks/{id} resets fields to zero/null if they are absent from the body — including percent_done, due_date, start_date, end_date, priority, hex_color, and description.

Always follow this pattern before updating any existing task:

1. GET /tasks/{id} — fetch current state

2. Build update body by starting from the full current object and overriding only the fields you intend to change

3. Always preserve these fields from the GET response (even if not changing them):

   • description
   • done
   • done_at
   • due_date
   • reminders
   • repeat_after / repeat_mode
   • priority
   • start_date
   • end_date
   • assignees
   • hex_color
   • percent_done
   • cover_image_attachment_id
   • is_favorite

   See: https://github.com/go-vikunja/vikunja/issues/1459

4. POST /tasks/{id} with the merged body

Never send a partial update body without first reading the task. This applies when bulk-updating multiple tasks too: GET each one individually before POSTing.

Example interactions

• "What tasks are due this week?" → GET /tasks/all with filter, format results
• "Mark task 42 as done" → POST /tasks/42 with {"done": true}
• "Add the 'urgent' label to task 17" → resolve label ID, PUT /tasks/17/labels
• "Assign me to task 5" → look up current user via GET /user, PUT /tasks/5/assignees
• "Set a reminder for task 8 in 2 hours" → compute absolute datetime, POST /tasks/8

Smart creation examples

• "Add a task called 'Buy milk' to Errands" → simple, no enrichment needed. Create directly with just the title.

• "In the Backend project add a task to migrate the auth service to JWT" → Fetch project tasks + labels. Notice existing auth-related tasks. Infer: title "Migrate auth service to JWT", description with checklist (design schema, update endpoints, write tests, update docs), priority medium (no urgency signal), labels matching "backend"/"auth" if available. Present proposal, wait for confirmation, then create + apply labels.

• "Add an urgent task in DevOps to fix the broken CI pipeline, it's blocking the release" → priority = urgent (5), infer relation blocking to any release-related task found in the project. Include a short description. Present proposal for confirmation before creating.

• "Create a task for next week Monday to review Q2 roadmap in Planning" → Parse "next week Monday" → set due_date. No start_date implied. If labels like "review" or "planning" exist, suggest them. Present proposal.

Read references/endpoints.md for exact request/response shapes.