vital git:20260920.ed0719fB

Immutable. This exact content never changes and is served at /api/v1/blob/10e6c35cf1f8808b.

---
name: vital
description: Operate the user's Vital personal OS (today, inbox, tasks, threads, habits, days, lists, tags, reports, search) through its HTTP API. Use when the user asks to add a task, capture a URL, tick a habit, manage threads or 日子, search inbox or reports, write a daily or weekly report, or otherwise manage Vital data. Requires a personal access token from Settings → 令牌. Use when the user runs /vital.
---

# Vital API

Read [references/api.md](references/api.md) before calling any endpoint. That file is generated from server routes and `@vital/dto` (`pnpm gen:vital-skill`). Do not invent fields or paths.

## Auth

1. If `VITAL_TOKEN` is missing, ask the user to create one in **设置 → 令牌** and paste it (or export the env var). Never ask them to paste their login password.
2. Base URL: `VITAL_API_URL` if set, otherwise `https://vital.aimo.plus`. Local dev is `http://127.0.0.1:3010`.
3. Send `Authorization: Bearer $VITAL_TOKEN` on every `/api/v1` call. Tokens start with `vt_`, do not expire until revoked, and do not use `/auth/refresh`.
4. Never print the full token in logs, commits, or chat. Refer to it by prefix only (`vt_xxxxxxxx`).

```bash
curl -sS -H "Authorization: Bearer $VITAL_TOKEN" -H "Content-Type: application/json" \
  "$VITAL_API_URL/api/v1/auth/me"
```

Errors are `{ "error": { "code": "...", "message": "...", "details": ... } }`. `401 INVALID_TOKEN` means the token is missing, revoked, or wrong.

## Workflows

Resolve request/response fields from `references/api.md`. Prefer these sequences:

**Today.** `GET /api/v1/today` — open threads, tasks, pulse, and now-recommendations.

**Tasks.** `GET /api/v1/tasks?listId=smart:today`. To add one, `GET /api/v1/lists`, pick the inbox or a user list UUID, then `POST /api/v1/tasks`. All-day due date: `dueYmd` as `YYYY-MM-DD` in the account timezone (do not send `dueAt` at the same time). Natural language: `POST /api/v1/tasks/from-text` (needs LLM settings). Complete with `POST /api/v1/tasks/:id/complete`.

**Threads.** `GET /api/v1/outcomes?status=open`. Create with `POST /api/v1/outcomes`. Drill-down: `GET /api/v1/outcomes/:id/detail`.

**Capture a document.** `POST /api/v1/inbox` with `title` and `markdown` or `extractedHtml`. The server stores TipTap `contentJson`. Read the body as Markdown: `GET /api/v1/inbox/:id/markdown` (list/sync omit the body). URL capture: `POST /api/v1/inbox/extract` then `POST /api/v1/inbox` with the preview. Convert to a task: `POST /api/v1/inbox/:id/convert`.

**Habits.** `GET /api/v1/habits`, then `POST /api/v1/habits/:id/tick`.

**Days.** `GET /api/v1/days`. Create with `POST /api/v1/days`.

**Search.** `POST /api/v1/search` with `{ "q" }`. Optional `types`: `task`, `inbox`, `report`. Grouped quick search: `GET /api/v1/search?q=`.

**Daily / weekly report.** `GET /api/v1/reports/current?type=daily` (or `weekly`). Save with `PATCH /api/v1/reports/:id` and the current `revision`. Agent notes (daily only): `POST /api/v1/reports/:id/generate`.

Do not use register/login/refresh, change-password, or LLM key endpoints unless the user explicitly asks. Do not create extra tokens unless asked.

When the catalog and a live 400 disagree, trust the live error `details` and the generated catalog — not memory.