vikunja-task-api（vikunja task API 文档）

Vikunja Task API Skill

Install

clawhub install ashanzzz-vikunja-task-api

Then set environment variables:

For detailed setup, see the Setup After Install section below.

Quick Setup

In your OpenClaw workspace, add to secure/api-fillin.env:

VIKUNJA_URL=http://your-vikunja-instance:3456
VIKUNJA_TOKEN=tk_xxxxxxxxxxxxx   # Optional: API token (recommended)
# VIKUNJA_USERNAME=your_username  # Optional: for login-based auth
# VIKUNJA_PASSWORD=your_password  # Optional: for login-based auth

2. Verify Connectivity

curl -s $VIKUNJA_URL/api/v1/info | jq

3. Install via ClawHub (if available)

clawhub install vikunja-task-api

Or manually clone into your skills directory:

git clone https://github.com/ashanzzz/openclaw-person-skills.git
export CLAWHUB_WORKDIR=$(pwd)/openclaw-person-skills

Installation (Human User)

Prerequisites

• Vikunja instance (self-hosted or cloud) — get it at https://vikunja.io/download
• API token from Vikunja: Settings → API Tokens → Create new token
• curl and jq installed on your system

Setup Steps

Step 1: Get your Vikunja URL

Note your Vikunja instance base URL, e.g.:

• Self-hosted: http://192.168.1.100:3456
• Cloud: https://vikunja.example.com

Step 2: Generate an API Token

1. Log in to Vikunja
2. Go to Settings → API Tokens
3. Click Create new token
4. Copy the token (starts with tk_)

Step 3: Test the Connection

export VIKUNJA_URL="http://your-vikunja-instance:3456"
export VIKUNJA_TOKEN="tk_your_token_here"

# Test (should return instance info)
curl -s "$VIKUNJA_URL/api/v1/info" | jq

# List your projects
curl -s "$VIKUNJA_URL/api/v1/projects" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title}'

Step 4: Optional — Install the Helper Script

Save vikunja.sh to a directory in your PATH for convenient CLI access:

curl -sL https://raw.githubusercontent.com/ashanzzz/openclaw-person-skills/main/skills/vikunja-task-api/vikunja.sh \
  -o /usr/local/bin/vikunja && chmod +x /usr/local/bin/vikunja

Then configure:

echo 'export VIKUNJA_URL="http://your-vikunja-instance:3456"' >> ~/.bashrc
echo 'export VIKUNJA_TOKEN="tk_your_token"' >> ~/.bashrc
source ~/.bashrc

Usage examples:

vikunja list                    # List all open tasks
vikunja due-today               # Tasks due today
vikunja create 9 "New task"    # Create task in project 9
vikunja done 123                # Mark task 123 as done
vikunja show 123                # Show task details

Use Vikunja as the source of truth for all task management. This skill supersedes any internal working-buffer tracking for user-visible tasks.

API Base

• Base URL: $VIKUNJA_URL/api/v1 (auto-normalized, no trailing slash)
• Auth: Authorization: Bearer <token> (JWT or API token)
• Token acquisition: POST /login with username + password

Authentication

Login (get JWT)

curl -X POST "$VIKUNJA_URL/api/v1/login" \
  -H "Content-Type: application/json" \
  -d '{"username":"USER","password":"PASS"}' | jq '.token'

API Token (recommended for automation)

Create a token in Vikunja UI: Settings → API Tokens. Then use:

export VIKUNJA_TOKEN="tk_xxxx"

Critical HTTP Method Rules (Must Remember!)

Core Endpoints

Projects

# List all projects
curl -s "$VIKUNJA_URL/api/v1/projects" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title,owner}'

# Create project (PUT, not POST!)
curl -X PUT "$VIKUNJA_URL/api/v1/projects" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Project Name","description":"","identifier":"","hex_color":""}' | jq '{id,title}'

# Get project details
curl -s "$VIKUNJA_URL/api/v1/projects/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Update project (POST)
curl -X POST "$VIKUNJA_URL/api/v1/projects/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"New Title","hex_color":"#ff0000"}' | jq '{id,title}'

# Delete project
curl -X DELETE "$VIKUNJA_URL/api/v1/projects/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

# Duplicate project
curl -X PUT "$VIKUNJA_URL/api/v1/projects/{id}/duplicate" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '{id,title}'

Tasks

# Get all open tasks (filter: done = false)
curl -s "$VIKUNJA_URL/api/v1/tasks" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  | jq '.[] | select(.done == false) | {id,title,due_date,project_id}'

# Get tasks by project
curl -s "$VIKUNJA_URL/api/v1/projects/{id}/tasks" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  | jq '.[] | {id,title,done,due_date}'

# Create task in project (PUT, not POST!)
curl -X PUT "$VIKUNJA_URL/api/v1/projects/{project_id}/tasks" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Task Title","description":"","due_date":"2026-04-30T23:59:00Z"}' | jq '{id,title}'

# Get task details
curl -s "$VIKUNJA_URL/api/v1/tasks/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Update task (POST) — including mark done
curl -X POST "$VIKUNJA_URL/api/v1/tasks/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"done":true,"title":"Updated Title"}' | jq '{id,done,done_at}'

# Delete task
curl -X DELETE "$VIKUNJA_URL/api/v1/tasks/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

# Bulk update tasks
curl -X POST "$VIKUNJA_URL/api/v1/tasks/bulk" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tasks":[{"id":1,"done":true},{"id":2,"done":true}]}' | jq

# Update task position (for drag-and-drop reordering)
curl -X POST "$VIKUNJA_URL/api/v1/tasks/{id}/position" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"position":0,"bucket_id":5}' | jq

# Duplicate task
curl -X PUT "$VIKUNJA_URL/api/v1/tasks/{id}/duplicate" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"project_id":9}' | jq '{id,title}'

Task Assignees

# Get assignees
curl -s "$VIKUNJA_URL/api/v1/tasks/{id}/assignees" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Add assignee
curl -X PUT "$VIKUNJA_URL/api/v1/tasks/{id}/assignees" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1}' | jq

# Bulk add assignees
curl -X POST "$VIKUNJA_URL/api/v1/tasks/{id}/assignees/bulk" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_ids":[1,2,3]}' | jq

# Remove assignee
curl -X DELETE "$VIKUNJA_URL/api/v1/tasks/{id}/assignees/{user_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Task Labels

# Get labels on a task
curl -s "$VIKUNJA_URL/api/v1/tasks/{id}/labels" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Add label to task
curl -X PUT "$VIKUNJA_URL/api/v1/tasks/{id}/labels" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label_id":5}' | jq

# Bulk update labels on task
curl -X POST "$VIKUNJA_URL/api/v1/tasks/{id}/labels/bulk" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"labels":[{"label_id":5},{"label_id":8}]}' | jq

# Remove label from task
curl -X DELETE "$VIKUNJA_URL/api/v1/tasks/{id}/labels/{label_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Task Comments

# Get comments
curl -s "$VIKUNJA_URL/api/v1/tasks/{id}/comments" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Create comment
curl -X PUT "$VIKUNJA_URL/api/v1/tasks/{id}/comments" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment":"This is a comment"}' | jq '{id,comment}'

# Update comment
curl -X POST "$VIKUNJA_URL/api/v1/tasks/{id}/comments/{comment_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"comment":"Updated comment"}' | jq

# Delete comment
curl -X DELETE "$VIKUNJA_URL/api/v1/tasks/{id}/comments/{comment_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Task Attachments

# List attachments
curl -s "$VIKUNJA_URL/api/v1/tasks/{id}/attachments" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Upload attachment
curl -X PUT "$VIKUNJA_URL/api/v1/tasks/{id}/attachments" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -F "file=@/path/to/file.pdf" | jq

# Delete attachment
curl -X DELETE "$VIKUNJA_URL/api/v1/tasks/{id}/attachments/{attachment_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Task Relations

# Create relation between two tasks
curl -X PUT "$VIKUNJA_URL/api/v1/tasks/{id}/relations" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"other_task_id":10,"relation_kind":"subtask|blocks|depends_on|related"}' | jq

# Remove relation
curl -X DELETE "$VIKUNJA_URL/api/v1/tasks/{id}/relations/{relation_kind}/{other_task_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Labels (standalone)

# List all labels
curl -s "$VIKUNJA_URL/api/v1/labels" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title,hex_color}'

# Create label
curl -X PUT "$VIKUNJA_URL/api/v1/labels" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Bug","hex_color":"#ff0000"}' | jq '{id,title}'

# Update label
curl -X PUT "$VIKUNJA_URL/api/v1/labels/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Feature","hex_color":"#00ff00"}' | jq

# Delete label
curl -X DELETE "$VIKUNJA_URL/api/v1/labels/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Project Views & Kanban Buckets

# List project views
curl -s "$VIKUNJA_URL/api/v1/projects/{id}/views" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title,kind}'

# List kanban buckets
curl -s "$VIKUNJA_URL/api/v1/projects/{id}/views/{view_id}/buckets" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title}'

# Create bucket
curl -X PUT "$VIKUNJA_URL/api/v1/projects/{id}/views/{view_id}/buckets" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"To Do"}' | jq '{id,title}'

# Update bucket
curl -X POST "$VIKUNJA_URL/api/v1/projects/{project_id}/views/{view_id}/buckets/{bucket_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"In Progress"}' | jq

# Delete bucket
curl -X DELETE "$VIKUNJA_URL/api/v1/projects/{project_id}/views/{view_id}/buckets/{bucket_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

# Move task to bucket (kanban drag-and-drop)
curl -X POST "$VIKUNJA_URL/api/v1/projects/{project}/views/{view}/buckets/{bucket}/tasks" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"task_id":123,"position":0}' | jq

Project Members

# List project users
curl -s "$VIKUNJA_URL/api/v1/projects/{id}/users" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Add user to project
curl -X PUT "$VIKUNJA_URL/api/v1/projects/{id}/users" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":1,"rights":1}' | jq   # rights: 0=read, 1=write, 2=admin

# Update user rights
curl -X POST "$VIKUNJA_URL/api/v1/projects/{project_id}/users/{user_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rights":2}' | jq

# Remove user from project
curl -X DELETE "$VIKUNJA_URL/api/v1/projects/{project_id}/users/{user_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Teams

# List all teams
curl -s "$VIKUNJA_URL/api/v1/teams" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,name}'

# Create team
curl -X PUT "$VIKUNJA_URL/api/v1/teams" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Engineering"}' | jq '{id,name}'

# Get team details
curl -s "$VIKUNJA_URL/api/v1/teams/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Add member to team
curl -X PUT "$VIKUNJA_URL/api/v1/teams/{id}/members" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"user@example.com"}' | jq

Project Shares (link sharing)

# List shares
curl -s "$VIKUNJA_URL/api/v1/projects/{id}/shares" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Create share link
curl -X PUT "$VIKUNJA_URL/api/v1/projects/{id}/shares" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"right":1}' | jq  # right: 0=read, 1=write

# Delete share
curl -X DELETE "$VIKUNJA_URL/api/v1/projects/{id}/shares/{share_id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Saved Filters

# Create saved filter
curl -X PUT "$VIKUNJA_URL/api/v1/filters" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"My Filter","filter":"done = false","project_id":0}' | jq '{id,title}'

# Get saved filter
curl -s "$VIKUNJA_URL/api/v1/filters/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Update saved filter
curl -X POST "$VIKUNJA_URL/api/v1/filters/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filter":"done = false && due_date < now"}' | jq

# Delete saved filter
curl -X DELETE "$VIKUNJA_URL/api/v1/filters/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Notifications

# Get notifications
curl -s "$VIKUNJA_URL/api/v1/notifications" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq '.[] | {id,title,message}'

# Mark all as read
curl -X POST "$VIKUNJA_URL/api/v1/notifications" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

# Mark one as (un)read
curl -X POST "$VIKUNJA_URL/api/v1/notifications/{id}" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_read":true}' | jq

Reactions

# Add reaction to entity (task, comment, etc.)
curl -X PUT "$VIKUNJA_URL/api/v1/{kind}/{id}/reactions" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reaction":"👍"}' | jq

# Get reactions
curl -s "$VIKUNJA_URL/api/v1/{kind}/{id}/reactions" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN" | jq

# Remove reaction
curl -X POST "$VIKUNJA_URL/api/v1/{kind}/{id}/reactions/delete" \
  -H "Authorization: Bearer $VIKUNJA_TOKEN"

Service Info

# Get instance info (no auth required)
curl -s "$VIKUNJA_URL/api/v1/info" | jq

Filtering Syntax

Vikunja uses a powerful filter language:

done = false
done = false && due_date < now
done = false && project_id = 9
done = false && due_date >= now/d && due_date < now/d + 1d
done = false && due_date < now + 1w
labels contains "Bug"
title contains "urgent"
priority > 0
assignee = <user_id>

Full docs: https://vikunja.io/docs/filters/

Helper CLI (vikunja.sh)

# List open tasks
vikunja.sh list --filter 'done = false'

# Overdue tasks
vikunja.sh overdue

# Due today
vikunja.sh due-today

# Show task
vikunja.sh show 123

# Mark done
vikunja.sh done 123

# Create task
vikunja.sh create 9 "New Task"

# Delete task
vikunja.sh delete 123

Task Display Format

Each task output:

<EMOJI> <DUE_DATE> - #<ID> <TASK>

• Emoji: first char of project title (first non-alphanumeric token for CJK/English)
• Default emoji: 🔨
• No due date: (no due)

Task Model (Complete Field Reference)

{
  "id": 123,
  "title": "Task Title",
  "description": "",
  "done": false,
  "done_at": null,
  "due_date": "2026-04-30T15:59:00Z",
  "project_id": 9,
  "repeat_after": 0,
  "priority": 0,
  "start_date": "0001-01-01T00:00:00Z",
  "end_date": "0001-01-01T00:00:00Z",
  "hex_color": "",
  "percent_done": 0,
  "created": "2026-03-31T12:00:00Z",
  "updated": "2026-03-31T12:00:00Z",
  "cover_image_url": null,
  "custom_fields": [],
  "缕": []
}

Important:

• due_date = 0001-01-01T00:00:00Z = no deadline
• priority: 0=none, 1=low, 2=medium, 3=high
• repeat_after: seconds until respawn (0 = not recurring)

Pagination

Endpoints that return lists support pagination via page and per_page query params.

Headers returned:

• x-pagination-total-pages
• x-pagination-result-count

Setup

# Recommended: write to secure/api-fillin.env
VIKUNJA_URL=http://192.168.8.11:3456
VIKUNJA_TOKEN=tk_xxxx

Differences from Typical REST APIs

Vikunja uses non-standard methods for create operations:

• PUT for create (projects, tasks, labels, comments, filters)
• POST for update
• DELETE for delete

This is because Vikunja's create endpoints return the created object with an ID, allowing you to immediately work with it — similar to a POST but idempotent.

Complete API Group Summary

Full OpenAPI spec: $VIKUNJA_URL/api/v1/docs.json