--- name: vikunja-api description: >- Interacts with Vikunja (self-hosted or cloud) via its REST API to manage tasks, projects, labels, and related resources. Uses VIKUNJA_BASE_URL and VIKUNJA_TOKEN from the process environment; fetches /api/v1/docs.json only when the conversation lacks enough API detail for the request. On failed requests, diagnoses missing config and points to persistent (global) env setup. Use when the user mentions Vikunja, wants task/project CRUD, imports, or API operations against their Vikunja instance. license: MIT compatibility: >- Any OS where the agent can run shell commands. Prefers curl (including curl.exe on Windows 10+); falls back to PowerShell Invoke-RestMethod on Windows if curl is unavailable. --- # Vikunja API Operate on **Vikunja** through its **HTTP API** (`/api/v1`). Prefer **existing conversation context** (paths, payloads, prior successful calls) when it is enough for the current request. If context is **insufficient** or **contradicted** by errors, align calls with the instance **OpenAPI** document (**§3**). ## 0. Default workflow (no pre-flight confirmation) **Do not** start with a dedicated “check env vars only” shell command. That pattern wastes turns and may trigger unnecessary **confirmations** in the host environment. Instead: 1. **Go straight to the user’s goal** — build the request using `VIKUNJA_BASE_URL` and `VIKUNJA_TOKEN` from the **same shell** the agent already uses (e.g. expand `$env:VIKUNJA_BASE_URL` in PowerShell, `$VIKUNJA_BASE_URL` in bash). 2. **Normalize base URL** when composing URLs: trim spaces; strip trailing `/`. Never put `/api/v1` inside the env value — append paths below. 3. **OpenAPI (`docs.json`) — only when needed:** fetch **§3** if the **current conversation** does not already give you enough to call the right **path, method, query, and body** for this request. If you already have that knowledge (from earlier in the thread, from the user’s pasted snippet, or from a prior successful call on the same base URL for the same operation type), **skip** downloading the spec to save time and tokens. 4. **Only if something fails** (see **§0.1**): run **diagnosis** and user guidance — especially **§6 (persistent / global first)**. Do not ask the user to paste secrets into chat. ### 0.1 What counts as failure (then diagnose) Run **env verification** (see **§0.1** steps) and **§6** only after one of these: - HTTP **401** / **403**, or missing/invalid auth behavior from the API. - Network errors (unreachable host, DNS, TLS), or **obviously wrong** URL (e.g. empty host after expanding env). - Shell/command errors that indicate **unset** variables (e.g. empty expansion, `curl` URL is empty). - Repeated **404** on `/api/v1/...`, or **400** with unclear validation — if you still lack a reliable path/body from context, **then** fetch **§3** before retrying; also verify base URL is the **instance origin**, not a subpath. **Diagnosis steps (after failure):** 1. Determine OS (see **§4**). 2. Verify `VIKUNJA_BASE_URL` and `VIKUNJA_TOKEN` exist and are non-empty in **that** shell **without** printing token value (e.g. test length / `Test-Path` style checks, or “is blank” only). 3. Tell the user **which** variable is missing or which class of error it is (`401` vs network vs blank URL). 4. Give **§6**: recommend **persistent user-level** (or system-level) setup for their OS; mention opening a **new shell** or restarting the **agent host process** after changing user/machine variables so it picks up updates. **Optional quick test (only when §6 was applied):** user may set vars for **current session** once to verify — see **§6** “Quick session-only test” at the end. ## 1. Environment variables (reference) | Variable | Meaning | |----------|---------| | `VIKUNJA_BASE_URL` | Instance **origin** only (scheme + host, optional port). **No** path suffix. Examples: `https://tasks.example.com`, `http://localhost:3456`. | | `VIKUNJA_TOKEN` | API token from Vikunja UI: **Settings → API Tokens**. Sent as `Authorization: Bearer `. | These are read **implicitly** when issuing HTTP requests. Formal “are they set?” checks belong in **§0.1**, not before the first attempt. ## 2. Token scope, expiry, and errors - **Effective permissions** depend entirely on the **Vikunja user** tied to that token and instance policies. The agent cannot “elevate” rights. - Tokens can be **revoked** or **expire** (per instance / admin rules). `401` / `403` may mean wrong token, expired token, or insufficient rights — say that plainly; suggest checking **Settings → API Tokens** and token scopes/labels if the UI offers them. - Do not blame Vikunja for “broken API” until configuration and auth are ruled out (**§0.1** + **§6**). ## 3. OpenAPI specification (when you need it) The live spec is **canonical** whenever you choose to load it — but loading it is **optional** if **§3.1** says you can skip. - **Spec URL:** `{VIKUNJA_BASE_URL}/api/v1/docs.json` - **Interactive docs (human):** `{VIKUNJA_BASE_URL}/api/v1/docs` ### 3.1 When to fetch `docs.json` (and when not to) **Fetch** (`GET` the JSON) when **any** of these holds: - You are **not sure** which endpoint, HTTP method, required fields, or query parameters apply. - The user asks for something **niche** (views, buckets, webhooks, migrations, etc.) and you have **no** matching detail in the thread. - An API response indicates **wrong shape** (e.g. unexpected **404** / **400** / empty list when the user expects data) and you do **not** already have the correct contract in context. **Skip the fetch** when **all** of these hold: - The conversation already contains **enough** concrete API usage for this step (your own or the user’s), **or** you are repeating the **same** operation pattern on the **same** `VIKUNJA_BASE_URL` you already used successfully earlier in the thread. **Workflow after you decide to fetch:** 1. `GET` `docs.json` with the same `Authorization: Bearer` header used for API calls (sending the header is fine even if docs are public). 2. Use it to choose **paths, methods, query params, and request bodies**. 3. If `docs.json` cannot be fetched: treat as **failure** → **§0.1** (may be bad base URL, network, or auth). ## 4. HTTP client by operating system Detect OS from the shell the agent uses (e.g. `uname` on Unix; `$IsWindows` / `cmd /c ver` on Windows). | OS family | Preferred tool | Notes | |-----------|----------------|--------| | **Windows** | `curl.exe` | Prefer **curl.exe** (bundled on Windows 10+). Use `-sS` for scriptable output. | | **Windows (fallback)** | PowerShell `Invoke-RestMethod` / `Invoke-WebRequest` | When `curl.exe` is missing or blocked. Headers: `-Headers @{ Authorization = "Bearer $env:VIKUNJA_TOKEN" }`. | | **Linux / macOS** | `curl` | Standard `-sS -H` patterns. | **Always** send for JSON APIs unless the spec says otherwise: ```http Authorization: Bearer Accept: application/json Content-Type: application/json ``` **Safety:** avoid printing full tokens in transcripts; redact in logs/examples. ### 4.1 Rich text: what format to send (`description`, `comment`, …) `docs.json` models these fields as plain **`string`** — it does **not** say “Markdown” or “HTML”. In practice the Vikunja **web UI** uses a **rich-text editor (Tiptap)** for long-form text, and values are stored and returned as **HTML fragments** (you will see tags like `

`, `