SecondBrain/reference/planka-v2-api-gotchas.md

summary	tags	scope	source	date	last_updated
Planka v2.1.1 API and Docker behaviors that differ from or are absent in its docs — auth/PAT limits, first-login terms flow, card-move and project-delete quirks, container uid.	type/reference tool/planka project/backlog-pilot domain/self-hosting	global	ovh-prod Planka deploy, 2026-07-08	2026-07-08	2026-07-08

Planka v2 API Gotchas (verified on v2.1.1)

Discovered during the ovh-prod deploy (2026-07-08), verified against a live v2.1.1 instance. Directly relevant to the backlog CLI in ~/dev/ruby-gems and any Planka automation.

1. No scoped API keys / PATs. Only POST /api/access-tokens with {emailOrUsername, password} → bearer JWT. Upstream issue #945 still open as of v2.1.1. Automation must hold real user credentials; a scoped-token proxy is the workaround.
2. First-ever login requires terms acceptance. The first POST /api/access-tokens returns E_FORBIDDEN with a pendingToken and step: "accept-terms". Flow: GET /api/terms → take item.signature → POST /api/access-tokens/accept-terms with {pendingToken, signature} → real token. Subsequent logins are normal.
3. Card move needs both fields. PATCH /api/cards/:id requires both listId and position; listId alone returns E_MISSING_OR_INVALID_PARAMS.
4. Project delete is not cascading. DELETE /api/projects/:id returns 422 "Must not have boards" — delete each board first.
5. Container uid. The ghcr.io/plankanban/planka image runs as uid 1000 (node). A bind-mounted /app/data must be chown 1000 or attachment/avatar uploads fail (container starts healthy either way — the failure is silent until first upload).

Deploy as-built details live in the repo: ovh-prod/docs/planka-deploy-prd.md. Related: vault-backlog-pilot-plan, backlog-system-options-research.