vikunja-task-api

# Vikunja Task API Skill

## Install

```bash
clawhub install ashanzzz-vikunja-task-api
```

Then set environment variables:

| Variable | Required | Description |
|----------|----------|-------------|
| `VIKUNJA_URL` | Yes | Vikunja 实例地址，如 `http://192.168.8.11:3456` |
| `VIKUNJA_TOKEN` | Recommended | API Token（优先）或用户名/密码 |
| `VIKUNJA_USERNAME` | Alt | 用户名（TOKEN 未设置时使用） |
| `VIKUNJA_PASSWORD` | Alt | 密码（TOKEN 未设置时使用） |

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

## Quick Setup

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

```bash
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

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

### 3. Install via ClawHub (if available)

```bash
clawhub install vikunja-task-api
```

Or manually clone into your skills directory:

```bash
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**

```bash
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:

```bash
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:

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

Usage examples:

```bash
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)
```bash
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:
```bash
export VIKUNJA_TOKEN="tk_xxxx"
```

## Critical HTTP Method Rules (Must Remember!)

| Operation | Method | Endpoint |
|-----------|--------|----------|
| Create project | **PUT** | `/projects` |
| Update project | **POST** | `/projects/{id}` |
| Delete project | **DELETE** | `/projects/{id}` |
| Create task | **PUT** | `/projects/{id}/tasks` |
| Update task | **POST** | `/tasks/{id}` |
| Delete task | **DELETE** | `/tasks/{id}` |
| Bulk update tasks | **POST** | `/tasks/bulk` |
| Get all tasks | **GET** | `/tasks` |
| Move task to bucket | **POST** | `/projects/{project}/views/{view}/buckets/{bucket}/tasks` |
| Create label | **PUT** | `/labels` |
| Update label | **PUT** | `/labels/{id}` |
| Delete label | **DELETE** | `/labels/{id}` |

## Core Endpoints

### Projects

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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)

```bash
# 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)

```json
{
  "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

```bash
# 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

| Group | Key Endpoints |
|-------|--------------|
| Auth | `POST /login` |
| Projects | CRUD: PUT/GET/POST/DELETE `/projects` |
| Tasks | CRUD: PUT(create in project), GET/POST/DELETE `/tasks` |
| Task Assignees | GET/PUT/POST/DELETE `/tasks/{id}/assignees` |
| Task Labels | GET/PUT/POST `/tasks/{id}/labels` |
| Task Comments | GET/PUT/POST/DELETE `/tasks/{id}/comments` |
| Task Attachments | GET/PUT/DELETE `/tasks/{id}/attachments` |
| Task Relations | PUT/DELETE `/tasks/{id}/relations` |
| Task Position | `POST /tasks/{id}/position` |
| Labels | CRUD: PUT/GET/PUT/DELETE `/labels` |
| Views & Buckets | GET `/projects/{id}/views`, CRUD `/buckets` |
| Project Members | GET/PUT/POST/DELETE `/projects/{id}/users` |
| Teams | CRUD: PUT/GET/POST/DELETE `/teams` |
| Project Shares | GET/PUT/DELETE `/projects/{id}/shares` |
| Saved Filters | CRUD: PUT/GET/POST/DELETE `/filters` |
| Notifications | GET/POST `/notifications` |
| Reactions | GET/PUT/POST `/reactions` |
| User Settings | Various `/user/settings/*` |
| Webhooks | CRUD `/webhooks` |
| Service | `GET /info` (no auth) |

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