NiaDocs
Latest
Menu

Nia documentation · Latest

API

Authenticate integrations and use the Nia V4 API reference.

Nia exposes a JSON API below /api. The web and native clients use the same API. This reference describes Nia V4; select the documentation matching your installed server. The product rename does not change existing nia-todo package identifiers, installation paths, API keys, or API URLs. /api/instance continues to advertise API version 1.

Create an API key

Create and revoke personal API keys from the user settings. When MFA is required, key management requires a fresh reauthentication step.

Send the key in the Authorization header:

curl https://todo.example.com/api/me \
  -H 'Authorization: ApiKey nt_REPLACE_WITH_YOUR_KEY'

Do not pass keys in query strings. Keep them in environment variables or a secret manager, and avoid printing them in CI logs.

Browser sessions

Interactive clients can authenticate through POST /api/login. Login can return either an access token or an MFA challenge. Browser mutations also use CSRF protection, so API keys are usually simpler for automation.

Main resources

The API includes resources for:

  • todos, subtasks, comments and attachments
  • projects, sections and personal Tasks workspaces
  • Shopping lists, sections, items and list-scoped stores
  • cookbooks, structured recipes, private images and recipe import previews
  • reminders and places
  • household ownership, direct sharing and invitations
  • account-wide module preferences and private destination memory
  • profile, sessions, passkeys and 2FA
  • admin configuration and users

The public instance-discovery endpoint is useful for connectivity checks:

curl https://todo.example.com/api/instance

Authentication

Most API endpoints require an authenticated user or administrator. Public endpoints are limited to login and recovery flows, OIDC bootstrap/callback routes, first-run setup, instance discovery, the VAPID public key, and selected runtime assets. The two first-run write endpoints do not require a user session, but they do require the installation’s X-Setup-Token header.

Interactive browser clients authenticate with a JWT and a CSRF cookie. State-changing requests must also send that value as X-CSRF-Token. User API keys use Authorization: ApiKey *** and are exempt from CSRF checks. Admin endpoints require an admin JWT; user API keys cannot access them.

Login

POST /api/login

Body

{
  "username": "demo",
  "password": "***"
}

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "csrf_token": "...",
  "user": {
    "id": 1,
    "username": "demo",
    "display_name": "Max Mustermann",
    "email": "user@example.com",
    "avatar_url": "/api/avatars/user-1.webp",
    "is_admin": true
  }
}

Login with 2FA Challenge

If 2FA is active for the user or globally enforced, POST /api/login can return a challenge instead of a token. Email code is a fallback only when no TOTP or passkey factor is available; it additionally requires a verified email, working SMTP, and a configured public base URL:

{
  "mfa_required": true,
  "challenge": {
    "challenge_token": "...",
    "methods": ["totp", "recovery_code"]
  },
  "state": {
    "enabled": true,
    "has_totp": true,
    "has_passkey": false,
    "recovery_codes_remaining": 8
  }
}

Completion:

POST /api/2fa/challenge/verify

{
  "challenge_token": "...",
  "method": "totp",
  "code": "123456",
  "remember_device": true
}

The response matches the normal login (access_token, csrf_token, user). The login challenge is consumed atomically and only creates login MFA assurance; sensitive actions such as password changes/API key management still require a fresh one-time MFA reauth. With remember_device=true, an HttpOnly trusted-device cookie is also set; it replaces later login MFA, but likewise does not count for sensitive actions.

POST /api/2fa/passkey/options and POST /api/2fa/passkey/verify complete the same login challenge via passkey. Passkey login requires user verification and also consumes the challenge exactly once.

Logout

POST /api/logout

Response

{ "logged_out": true }

For a regular session JWT, logout revokes only the current device session. A legacy JWT without a session ID increments the user’s token version and therefore invalidates all user JWTs. Missing or already invalid credentials still receive the neutral success response.

Current User

GET /api/me

Response

{
  "id": 1,
  "username": "demo",
  "display_name": "Max Mustermann",
  "email": "user@example.com",
  "avatar_url": "/api/avatars/user-1.webp",
  "avatar_updated_at": "2026-05-21T00:00:00+00:00",
  "is_admin": true,
  "disabled_modules": [],
  "braindump_enabled": true,
  "braindump_learning_enabled": true,
  "attachments_enabled": true,
  "attachment_usage_bytes": 1048576,
  "attachment_quota_bytes": 5368709120,
  "attachment_remaining_bytes": 5367660544,
  "attachment_max_upload_bytes": 26214400,
  "attachments_allowed_types": [".png", ".jpg", ".jpeg", ".gif", ".webp", ".pdf"]
}

Attachment fields describe the current user’s effective upload policy and storage usage. A quota of 0 means uploads are locked/full for that user. disabled_modules is the same account-wide preference exposed at /api/me/modules; braindump_learning_enabled reflects the shared destination-memory switch.

Dashboard Preferences

GET /api/me/dashboard-preferences

Returns the account-wide synchronization state and the stored dashboard configuration for each workspace. Authentication works with an interactive user session or a personal API key.

Response

{
  "enabled": true,
  "preferences": {
    "12": {
      "version": 3,
      "compactDisplay": false,
      "groupByStatus": true,
      "showFocus": true,
      "showActiveProjects": true,
      "showProjectWidgets": true,
      "projectScope": {
        "mode": "all",
        "projectIds": []
      },
      "stats": ["total", "pending", "in_progress", "overdue"],
      "focusItems": ["overdue", "due_today", "due_week", "high_priority"],
      "hideEmptyFocusItems": false,
      "activeProjects": {
        "limit": 4,
        "sort": "recent"
      }
    }
  }
}

The keys below preferences are workspace IDs. When synchronization is disabled, the response is { "enabled": false, "preferences": {} }.

PUT /api/me/dashboard-preferences

Enables or disables synchronization and replaces the supplied workspace configurations.

Body

{
  "enabled": true,
  "preferences": {
    "12": {
      "version": 3,
      "compactDisplay": false,
      "groupByStatus": true,
      "showFocus": true,
      "showActiveProjects": true,
      "showProjectWidgets": true,
      "projectScope": {
        "mode": "include",
        "projectIds": [7, 9]
      },
      "stats": ["total", "pending", "due_today", "done"],
      "focusItems": ["overdue", "due_today", "high_priority"],
      "hideEmptyFocusItems": true,
      "activeProjects": {
        "limit": 6,
        "sort": "alphabetical"
      }
    }
  }
}

Set enabled to false to disable synchronization and delete all dashboard preferences stored for the account. The server validates workspace ownership, referenced projects, allowed values and payload size. The response uses the same shape as the GET endpoint and is also broadcast to the user’s open WebSocket connections.

Server Update Status

GET /api/server-update

Returns the server’s retained update-check result for the authenticated user. The endpoint accepts both an interactive user session and a personal API key:

curl https://todo.example.com/api/server-update \
  -H 'Authorization: ApiKey nt_REP..._KEY'

Response

{
  "current_version": "3.2.1",
  "latest_version": "3.2.2",
  "update_available": true,
  "stale": false
}

current_version is the running server/Web-App version. latest_version is the newest retained release from the server-side update check. Either version can be null when it cannot be determined. stale=true means that no current successful check result exists yet or that the most recent check failed, so the retained latest-version information may not reflect the current upstream release. When versions are missing or cannot be compared, update_available is false; this does not by itself confirm that the server is current.

Change Own Profile

PATCH /api/me/profile

Body

{ "display_name": "Max Mustermann" }

Response

{
  "id": 1,
  "username": "demo",
  "display_name": "Max Mustermann",
  "email": "user@example.com",
  "avatar_url": "/api/avatars/user-1.webp",
  "avatar_updated_at": "2026-05-21T00:00:00+00:00",
  "is_admin": true
}

Upload Own Avatar

PUT /api/me/avatar

Request

  • Body: raw image data
  • Content-Type: image/jpeg, image/png, image/webp, image/gif, image/heic or image/heif
  • Maximum size: 5 MiB

Storage

  • File: ${NIA_TODO_AVATAR_DIR}/user-{id}.webp. Without that override, avatars are stored below ${NIA_TODO_DATA_DIR}/avatars (typically /data/avatars in Docker and /var/lib/nia-todo/avatars in the Debian package).
  • DB: only avatar_url and avatar_updated_at

Response

{
  "avatar_url": "/api/avatars/user-1.webp",
  "avatar_updated_at": "2026-05-21T00:00:00+00:00"
}

Change Own Email

PATCH /api/me/email

Body

{ "email": "neue@example.com" }

Validation

  • Required field
  • Must be a valid email address
  • Uniqueness is checked case-insensitively. To avoid account enumeration, an address already used by another account receives a neutral successful response with email_verification_delivery: "unavailable".

Response (with SMTP configured)

{
  "email": null,
  "pending_email": "neue@example.com",
  "email_verification_required": true,
  "email_verification_delivery": "email"
}

Response (without SMTP)

{
  "email": "neue@example.com",
  "pending_email": null,
  "email_verification_required": false,
  "email_verification_delivery": "unverified_no_smtp"
}

Note: With SMTP, the new email is stored as pending_email and a verification email is sent. The old email remains active until verification. Without SMTP, the email is active immediately, but not verified (cannot be used for login/sharing).

Change Own Password

POST /api/me/change-password

Body

{ "old_password": "alt123!", "new_password": "neu123!" }

Response

{ "message": "Password changed. Please sign in again." }

Changing the password increments the user’s token version and requires a new login. Accounts subject to MFA must provide a fresh, single-use MFA action grant.

Two-Factor Authentication

2FA Status

GET /api/me/2fa

Returns enabled/available factors, recovery-code count, global requirement, and passkey count. The status contains no secrets and remains readable with a valid interactive JWT even when no fresh action reauth is present, so clients can start the appropriate reauth flow.

Start/Confirm TOTP

POST /api/me/2fa/totp/start returns secret and otpauth_url.

POST /api/me/2fa/totp/confirm

{ "secret": "BASE32...", "code": "123456", "password": "..." }

Activates TOTP after password confirmation and returns new recovery codes exactly once, plus a fresh MFA JWT. The endpoint may also be used with an enrollment-only JWT; in this state, no additional MFA reauth is possible or required. Recovery codes are backup factors for TOTP/passkey, not the primary 2FA state.

Disable 2FA / Revoke Factors / Regenerate Recovery Codes

  • POST /api/me/2fa/disable — requires a fresh one-time MFA reauth, revokes trusted devices, passkeys, and recovery codes.
  • DELETE /api/me/2fa/totp — revokes the configured TOTP secret, requires a fresh one-time MFA reauth. If no primary factor (TOTP/passkey) remains afterwards, recovery codes are automatically revoked and user-side 2FA is disabled; with a global policy, email-code MFA can still apply as a fallback.
  • POST /api/me/2fa/recovery-codes/regenerate — requires a fresh one-time MFA reauth and at least one primary factor (TOTP or passkey), returns new codes exactly once.
  • POST /api/me/2fa/reauth — verifies TOTP, recovery code, or email code with attempt lockout and issues a JWT with a single-use MFA action grant. Reauth buckets are consumed after success; email reauth codes are invalidated and TOTP reauth timesteps are accepted only once.
  • POST /api/me/2fa/reauth/email/start — sends an email reauth code if email code is the available factor.
  • POST /api/me/2fa/reauth/passkey/options and POST /api/me/2fa/reauth/passkey/verify — passkey reauth for passkey-only users.

Active Device Sessions / Trusted Devices

  • GET /api/me/2fa/trusted-devices — lists active signed-in device sessions for the current user, not only trusted 2FA devices. Sessions can optionally be linked to a trusted 2FA-remember device and include metadata such as user agent, last use, expiry, and whether it is the current session.
  • DELETE /api/me/2fa/trusted-devices/{id} / DELETE /api/me/2fa/trusted-devices/{device_id} — revokes one device session using a normal interactive JWT plus CSRF protection; no fresh MFA action grant is required because this only reduces account access. If the session was linked to a trusted 2FA device, that trusted-device token is revoked too. Revoking the current session signs out the current browser/app.
  • DELETE /api/me/2fa/trusted-devices — revokes all active user sessions and all trusted 2FA devices for the current user, then signs out the current browser/app.

Passkeys

  • GET /api/me/passkeys — list own passkeys.
  • POST /api/me/passkeys/options with { "name": "Laptop" } — prepare registration options/challenge; allowed with enrollment-only JWT or fresh MFA reauth.
  • POST /api/me/passkeys/verify with { "name": "Laptop", "challenge": "...", "credential": {...}, "password": "..." } — complete registration; allowed with enrollment-only JWT or single-use MFA action grant and returns a fresh MFA JWT.
  • POST /api/2fa/passkey/options with { "challenge_token": "..." } — create an assertion challenge for an MFA login.
  • POST /api/2fa/passkey/verify with { "challenge_token": "...", "credential": {...}, "remember_device": false } — complete the MFA login.
  • POST /api/me/2fa/reauth/passkey/options prepares passkey reauthentication; POST /api/me/2fa/reauth/passkey/verify accepts { "challenge": "...", "credential": {...} }.
  • DELETE /api/me/passkeys/{id} / DELETE /api/me/passkeys/{passkey_id} — revoke passkey, requires a fresh one-time MFA reauth. If no primary factor (TOTP/passkey) remains afterwards, recovery codes are automatically revoked and user-side 2FA is disabled; with a global policy, email-code MFA can still apply as a fallback.

Passkeys are bound to the configured public base URL (public_base_url). HTTPS is mandatory for non-localhost hosts; without public_base_url, production passkey flows for non-localhost hosts fail closed. Windows Native uses a native WebAuthn bridge with server-provided origin; for this, the server URL configured in the app must match the public_base_url origin/RP ID.

Android Native uses AndroidX Credential Manager. Each self-hosted server instance serves /.well-known/assetlinks.json for the bundled Android app:

  • Package: bundled release app ID
  • Release certificate: bundled release certificate fingerprint
  • Relations: delegate_permission/common.get_login_creds and delegate_permission/common.handle_all_urls

In addition to the HTTPS web origin, the server accepts the pinned Android app origin android:apk-key-hash:..., while the RP ID hash continues to be checked against public_base_url. Self-hosters run their own server and connect the bundled Android app to their server URL. Custom package names, F-Droid/re-sign builds, and signing-key rotation are not part of the current 2.0 model and will later need an explicit config/migration strategy.

Admin Policy

  • GET /api/admin/2fa-policy
  • PATCH /api/admin/2fa-policy with { "required": true }
  • GET /api/admin/users additionally includes 2FA, passkey and API-key status fields.
  • POST /api/admin/users/{user_id}/2fa/reset — resets a user’s factors, recovery codes, passkeys, and trusted devices, increments token_version, and thereby invalidates existing interactive JWT sessions. Open WebSocket connections of the user additionally receive {"type":"session_invalidated","reason":"two_factor_reset"} and are then closed server-side.

Security-sensitive account actions require a fresh, single-use MFA action grant for 2FA-required accounts. Login MFA and trusted devices count only for app access, not for sensitive actions. Initial TOTP/passkey setup is the exception: with an enrollment-only JWT, password confirmation is sufficient because no second factor exists yet. Reauth codes are hardened against replay: email reauth codes are deleted after success, TOTP reauth can issue only one grant per timestep, recovery codes are table-backed and consumed single-use. API keys (ApiKey nt_...) are intentionally exempt from interactive MFA during use as machine tokens. Creating and revoking own API keys always requires a new reauth for MFA-required accounts; the settings UI starts a reauth flow when needed. Existing API keys are not automatically revoked when MFA is enabled; the admin UI shows active keys as a warning. An enrollment-only token is issued whenever MFA is required—by user setting or global policy—but no usable challenge factor is available. Email-code fallback is a transitional/login fallback, not a user-configured primary factor.

Email / SMTP

Verify Own Email

POST /api/me/email/verify

Body

{ "token": "abc123..." }

Response

{ "message": "Email verified." }

Note: One-time token from the verification email. After successful verification, pending_email becomes email and email_verified_at is set.

Request Password Reset (public)

POST /api/password-setup/request

Body

{ "identifier": "user@example.com" }

Response (always neutral)

{
  "message": "Falls ein passendes Konto existiert, wurde eine E-Mail gesendet."
}

Note: For security reasons, a neutral response is always returned (no enumeration). Reset emails are sent only to verified emails.

Fetch Password Setup Features (public)

GET /api/password-setup/features

Response

{
  "email_configured": true,
  "password_reset_available": true
}

GET /api/password-setup/validate?token=...

Response (valid)

{
  "valid": true,
  "username": "demo",
  "display_name": "Max Mustermann",
  "purpose": "reset",
  "expires_at": "2026-05-24 12:00:00"
}

POST /api/password-setup/resend

Body

{ "token": "..." }

Response

{
  "message": "Neuer Link wurde per E-Mail gesendet.",
  "password_setup_delivery": "email",
  "password_setup_expires_hours": 24
}

POST /api/admin/users/{user_id}/password-link

Response (with SMTP + verified email)

{
  "email_sent": true,
  "message": "Passwort-Setup-Link wurde per E-Mail gesendet."
}

Response (without SMTP or unverified email)

{
  "email_sent": false,
  "password_setup_url": "https://todo.example.com/set-password?token=..."
}

Note: Admins can generate password setup links for users. With SMTP + verified email, the link is sent by email; otherwise it is returned as a manual link.

Fetch Instance Configuration

GET /api/admin/instance-config

Response

{
  "public_base_url": "https://todo.example.com",
  "allowed_origins": ["https://todo.example.com"],
  "trusted_proxies": ["192.0.2.10"],
  "update_analytics_enabled": true
}

Update Instance Configuration

PATCH /api/admin/instance-config

Body

{
  "public_base_url": "https://todo.example.com",
  "allowed_origins": ["https://todo.example.com"],
  "trusted_proxies": ["192.0.2.10"],
  "update_analytics_enabled": false
}

Note: public_base_url is used among other things for password/invitation links and production passkey origin/RP ID validation. CORS accepts only configured origins; forwarded headers are evaluated only from trusted proxies. update_analytics_enabled is optional in PATCH requests; when omitted, the stored privacy choice is preserved. Disabling it suppresses only the Umami analytics event and leaves update checks and notifications enabled.

Admin: Email Configuration

Fetch SMTP Configuration

GET /api/admin/email-config

Response

{
  "smtp_enabled": true,
  "smtp_host": "smtp.example.com",
  "smtp_port": 587,
  "smtp_security": "starttls",
  "smtp_auth_enabled": true,
  "smtp_username": "nia@example.com",
  "smtp_password_configured": true,
  "mail_from_address": "nia@example.com",
  "mail_from_name": "Nia",
  "mail_reply_to": "",
  "password_link_ttl_hours": 24
}

Note: smtp_password_configured is a boolean field; the actual password is never returned.

Update SMTP Configuration

PATCH /api/admin/email-config

Body

{
  "smtp_enabled": true,
  "smtp_host": "smtp.example.com",
  "smtp_port": 587,
  "smtp_security": "starttls",
  "smtp_auth_enabled": true,
  "smtp_username": "nia@example.com",
  "smtp_password_secret": "***",
  "mail_from_address": "nia@example.com",
  "mail_from_name": "Nia"
}

Response

Returns the complete sanitized SMTP configuration shown by GET /api/admin/email-config. Omitting smtp_password_secret or sending null preserves the stored secret; an empty string clears it.

Send Test Email

POST /api/admin/email-config/test

Body

{ "to": "user@example.com" }

Response

{ "message": "Test email sent." }

SMTP failures use the normal HTTP error response rather than a successful { "ok": false } payload.

First-run Setup

First-run setup is a two-step bootstrap flow protected by one installation-specific token. The token is written to the service log and to the data directory when an empty instance starts. The API never returns it.

Use the same required header for both write steps:

X-Setup-Token: <first-run-token>

A missing or invalid token returns HTTP 403. The token remains valid after step 1 and across service restarts, so an interrupted setup can continue. It is deleted only after the first user has been committed successfully. After completion, the token cannot be reused and both write endpoints reject another bootstrap attempt.

Setup Status

GET /api/setup/status

This public status endpoint never discloses the token.

{
  "setup_complete": false,
  "has_users": false,
  "setup_token_required": true,
  "admin_password_set": false
}

Step 1: Set Admin Password

POST /api/setup/admin

{ "admin_password": "***" }

Response

{ "message": "Admin password set" }

Step 2: Create First User

POST /api/setup/first-user

This step must follow the admin-password step. Calling it first returns HTTP 409.

{
  "username": "demo",
  "email": "user@example.com",
  "password": "***",
  "display_name": "Max Mustermann"
}

Response

{
  "message": "First user created",
  "user": {
    "id": 1,
    "username": "demo",
    "email": "user@example.com",
    "display_name": "Max Mustermann"
  }
}

Admin

Admin Login

POST /api/admin/login

Body

{ "password": "***" }

Response

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "admin": true,
  "csrf_token": "..."
}

Admin Logout

POST /api/admin/logout

Invalidates all admin sessions by increasing the admin token version.

Attachment Configuration

GET /api/admin/attachment-config

Response

{
  "enabled": true,
  "allowed_types": [".png", ".jpg", ".jpeg", ".gif", ".webp", ".pdf"],
  "default_quota_bytes": 5368709120
}

PATCH /api/admin/attachment-config

Body

{
  "enabled": true,
  "allowed_types": ["png", "jpg", "jpeg", "gif", "webp", "pdf"],
  "default_quota_bytes": 5368709120
}

allowed_types may be bare extensions or dot-prefixed extensions; the server normalizes them to dot-prefixed lowercase values. default_quota_bytes=0 makes the global default quota locked/full unless a user override is set.

List Users

GET /api/admin/users

Response

{
  "users": [
    {
      "id": 1,
      "username": "demo",
      "display_name": "Max Mustermann",
      "email": "user@example.com",
      "is_admin": true,
      "attachment_quota_bytes": null,
      "attachment_quota_effective_bytes": 5368709120,
      "attachment_usage_bytes": 1048576
    }
  ]
}

Create User

POST /api/admin/users

Body

{
  "username": "neu",
  "display_name": "Neuer User",
  "email": "neu@example.com"
}

The admin no longer sets a password directly. A one-time password setup link is generated during creation.

Validation

  • email is required
  • Must be a valid email address
  • Must be unique

Response (email delivered)

{
  "id": 2,
  "username": "neu",
  "display_name": "Neuer User",
  "email": "neu@example.com",
  "language": "de",
  "braindump_enabled": false,
  "created_at": "2026-05-20T21:30:00Z",
  "password_setup_expires_hours": 24,
  "password_setup_delivery": "email",
  "message": "Invitation email sent."
}

If email delivery is unavailable or fails, password_setup_delivery is manual, the message is Password link created., and the response additionally contains password_setup_url. The URL is deliberately omitted after successful email delivery.

Update User

PATCH /api/admin/users/{id}

Body

{ "email": "neu@example.com", "attachment_quota_bytes": 1073741824 }

Optionally, display_name, username, braindump_enabled, and attachment_quota_bytes can be provided as well. attachment_quota_bytes=null uses the global default; 0 locks uploads for that user.

Response

{ "id": 2, "email": "neu@example.com", "display_name": null }

Delete User

DELETE /api/admin/users/{id}

Response

{ "deleted": 2 }

POST /api/admin/users/{id}/change-password / POST /api/admin/users/{user_id}/change-password

Compatibility endpoint: admins no longer set passwords directly. The endpoint generates a one-time link.

Response

{
  "password_setup_url": "https://todo.example.com/set-password?token=...",
  "password_setup_expires_hours": 24
}

POST /api/admin/users/{id}/password-link

Response

{
  "password_setup_url": "https://todo.example.com/set-password?token=...",
  "password_setup_expires_hours": 24
}

POST /api/password-setup/complete

Body

{ "token": "...", "password": "NeuesPasswort123!" }

Response

{ "message": "Passwort gesetzt" }

Links are valid once. Their lifetime defaults to 24 hours and can be configured by an administrator from 1 to 168 hours.

Change Admin Password

POST /api/admin/change-password

Body

{
  "old_password": "alt123!",
  "new_password": "neu123!"
}

Response

{ "message": "Admin password changed. Please sign in again." }

The change increments the admin token version and invalidates all existing admin JWTs.

API Keys

List

GET /api/me/api-keys

Response

{
  "api_keys": [
    {
      "id": 1,
      "name": "Nia-Integration",
      "key_prefix": "nt_e3b",
      "created_at": "2026-05-16T11:30:00",
      "last_used_at": "2026-05-16T12:00:00",
      "revoked_at": null
    }
  ]
}

Create

POST /api/me/api-keys

Body

{ "name": "Nia-Integration" }

Response

{
  "id": 12,
  "name": "Nia-Integration",
  "prefix": "nt_abcd1234",
  "key": "nt_...",
  "created_at": "2026-05-16T11:30:00+00:00"
}

The full key is shown only once during creation.

Revoke

DELETE /api/me/api-keys/{id} / DELETE /api/me/api-keys/{key_id}

Response

{ "revoked": 12 }

Auth with API Key

Authorization: ApiKey nt_...

Notes

  • API keys are bound to the user
  • revoked keys are invalid immediately
  • last_used_at is maintained
  • API keys bypass CSRF only with Authorization: ApiKey ***
  • Authorization: Bearer *** and X-API-Key are not supported as API-key authentication

Todos

List

GET /api/todos

Query

  • status=pending|in_progress|done
  • project_id=2
  • section_id=1

Response

{
  "todos": [
    {
      "id": 1,
      "title": "Nia einrichten",
      "description": "",
      "priority": 3,
      "status": "pending",
      "due_date": "2026-05-14T10:00:00+00:00",
      "completed_at": null,
      "project_id": 3,
      "section_id": null,
      "project_name": "Arbeit",
      "section_name": null,
      "created_at": "2026-05-12T21:39:40",
      "updated_at": "2026-05-12T21:39:40",
      "reminders": [],
      "subtasks": [
        {
          "id": 10,
          "title": "Backup prüfen",
          "is_done": false,
          "sort_order": 0
        }
      ]
    }
  ]
}

Single Todo

GET /api/todos/{id} / GET /api/todos/{todo_id}

Response

{
  "id": 1,
  "title": "Nia einrichten",
  "description": "",
  "priority": 3,
  "status": "pending",
  "project_id": 3,
  "section_id": null,
  "reminders": [],
  "subtasks": []
}

Create

POST /api/todos

Body

{
  "title": "Wäsche waschen",
  "description": "Nicht vergessen",
  "priority": 3,
  "project_id": 2,
  "section_id": 1,
  "due_date": "2026-05-14T10:00:00Z",
  "remind_at": "2026-05-14T09:00:00Z",
  "recurring_rule": {"frequency": "daily", "interval": 1, "timezone": "Europe/Berlin"},
  "status": "pending",
  "is_pinned": false,
  "client_mutation_id": "laundry-create-1",
  "location_reminder": null,
  "subtasks": [
    {"title": "Waschmaschine starten", "is_done": false},
    {"title": "Wäsche aufhängen", "is_done": false}
  ]
}

Fields

  • title string, required
  • description string, optional
  • priority int, optional, 1..4 when creating a todo
  • status string, optional, pending|in_progress|done
  • is_pinned bool, optional
  • project_id int, optional
  • section_id int, optional
  • due_date ISO-8601, optional, valid year 1900..9999
  • remind_at ISO-8601, optional, valid year 1900..9999
  • recurring_rule object, optional; supports frequency=daily|weekly|monthly|yearly, interval=1..999, and an optional IANA timezone other than localtime. Requires due_date. When a recurring todo is completed, the API marks the current todo done and creates the next pending occurrence.
  • location_reminder object, optional; see Places and location reminders.
  • subtasks array, optional; checklist items with title, is_done, and optional sort_order. They are lightweight checklist entries, not full child todos. REST list/get/create/update responses and WebSocket todo sync payloads include subtasks consistently.
  • confirm_incomplete_subtasks_completion bool, optional; required when setting status=done while any subtask remains open.
  • client_mutation_id string, optional, at most 200 characters; stable per logical create, with deletion-safe replay as described under retry contracts. The legacy _tempId create alias remains accepted.
  • routing_feedback object, optional; explicitly teaches selected fields in the shared destination memory. It is also accepted on normal todo updates.

Response

{
  "id": 17,
  "title": "Wäsche waschen",
  "status": "pending"
}

Update

PATCH /api/todos/{id} / PATCH /api/todos/{todo_id}

Body

  • editable todo fields from POST, all optional; the create-only client_mutation_id is not a general PATCH idempotency key
  • status=done sets completed_at
  • updating subtasks replaces the todo checklist with the provided ordered list
  • omitting subtasks leaves the existing checklist unchanged; sending an empty array clears it
  • setting status=done while subtasks are open returns HTTP 409 unless confirm_incomplete_subtasks_completion=true is included

Response

{
  "id": 17,
  "title": "Wäsche waschen",
  "status": "done"
}

Delete

DELETE /api/todos/{id} / DELETE /api/todos/{todo_id}

Response

{ "deleted": 17 }

Deleting a todo through this endpoint also removes its attachment metadata and stored attachment files.

Subtasks

Accepted members of a shared project have the same todo and subtask write access as the owner; there is currently no read-only project role.

  • POST /api/todos/{todo_id}/subtasks with { "title": "Backup prüfen", "is_done": false, "sort_order": 0, "client_mutation_id": "optional-stable-id" }
  • PATCH /api/todos/{todo_id}/subtasks/{subtask_id} with any of title, is_done, or sort_order
  • DELETE /api/todos/{todo_id}/subtasks/{subtask_id}

Titles are trimmed, must not be empty, and are limited to 500 characters. Replacing the embedded subtasks array accepts at most 100 entries. client_mutation_id is optional, limited to 200 characters and intended as a stable idempotency key for retried create requests. Use a new key for each logical subtask creation. Repeating the create for the same Todo and authenticated user returns the originally created subtask without applying different title, completion or sort values from the retry. The key is accepted only as create input and is not included in the returned subtask resource. Create and update return { "subtask": {...}, "todo": {...} }; delete returns { "deleted": <subtask_id>, "todo": {...} }. Changes emit todo_subtask_create, todo_subtask_update, and todo_subtask_delete realtime events.

Comments

  • POST /api/todos/{todo_id}/comments with { "body": "...", "client_mutation_id": "optional-stable-id" }
  • PATCH /api/todos/{todo_id}/comments/{comment_id} with { "body": "..." }
  • DELETE /api/todos/{todo_id}/comments/{comment_id}

Comment bodies are trimmed, must not be empty, and are limited to 5000 characters. Anyone with access to the todo may comment. Only the comment author may edit it; the comment author or todo creator may delete it. client_mutation_id is optional, limited to 200 characters and acts as an idempotency key for create retries by the same author on the same Todo. Use a new key for each logical comment creation. A retry with the same key returns the originally created comment without applying a different body, and the key is not included in the returned comment resource. Create and update return { "comment": {...}, "todo": {...} }; delete returns { "deleted": <comment_id>, "todo": {...} }. Changes emit the corresponding todo_comment_* realtime events.

Attachment Usage

GET /api/todos/attachments/usage

Returns the current user’s effective attachment upload policy and usage.

Response

{
  "enabled": true,
  "used_bytes": 1048576,
  "quota_bytes": 5368709120,
  "remaining_bytes": 5367660544,
  "allowed_types": [".png", ".jpg", ".jpeg", ".gif", ".webp", ".pdf"],
  "max_upload_bytes": 26214400
}

List Attachments

GET /api/todos/{todo_id}/attachments

Requires read access to the todo/project.

Response

{
  "attachments": [
    {
      "id": 12,
      "todo_id": 17,
      "user_id": 1,
      "original_filename": "screenshot.png",
      "content_type": "image/png",
      "size_bytes": 18342,
      "created_at": "2026-06-17T10:00:00+00:00"
    }
  ]
}

Upload Attachment

POST /api/todos/{todo_id}/attachments

Requires write access to the todo/project. Existing attachments remain readable/downloadable when uploads are disabled, but new uploads are rejected.

Request

  • Body: raw file bytes
  • Headers:
    • Content-Type: declared MIME type
    • X-Nia-Filename (or X-File-Name / X-Filename): original filename
  • Limits:
    • maximum 20 attachments per todo
    • maximum file size from server policy
    • allowed extension allowlist from attachment config
    • default/per-user quota
    • server-side magic-byte validation for PNG/JPEG/GIF/WebP/PDF/ZIP and hard blocking for active content such as SVG/HTML/JavaScript

Response

{
  "attachment": {
    "id": 12,
    "todo_id": 17,
    "original_filename": "screenshot.png",
    "content_type": "image/png",
    "size_bytes": 18342
  },
  "todo": { "id": 17, "attachments_count": 1 },
  "usage": { "used_bytes": 18342, "quota_bytes": 5368709120 }
}

Download Attachment

GET /api/todos/{todo_id}/attachments/{attachment_id}/download

Requires read access to the todo/project and returns the stored file with the original filename in Content-Disposition.

Delete Attachment

DELETE /api/todos/{todo_id}/attachments/{attachment_id}

Requires write access to the todo/project. Shared/invited project members with current write access can delete attachments.

Response

{ "deleted": 12, "todo": { "id": 17, "attachments_count": 0 } }

Uploads count against the uploader’s quota only while that uploader can currently access the todo. Losing the last access source, including household membership or a direct project grant, stops quota accounting for those files; regaining access restores it. The attachment remains with the todo and accessible to its current participants, including users whose own uploads are disabled or have no quota. Quota is an upload policy, not a download permission. Recipe title images use separate storage and do not consume this quota. Attachment create/delete actions emit realtime delta events (todo_attachment_create, todo_attachment_delete).

Workspaces

List

GET /api/workspaces

Response

{
  "workspaces": [
    {
      "id": 1,
      "name": "Privat",
      "color": "#10b981",
      "icon": "home",
      "sort_order": 0,
      "is_default": 1
    }
  ]
}

Notes

  • Each user has a default workspace and one inbox per workspace.
  • On first fetch, a missing default workspace and its inbox are automatically repaired/created. Existing non-default workspaces are not scanned for repair.

Create

POST /api/workspaces

Body

{ "name": "Arbeit", "color": "#6366f1", "icon": "briefcase", "sort_order": 10 }

Response

{ "id": 2, "name": "Arbeit", "color": "#6366f1", "icon": "briefcase", "is_default": 0 }

Update

PATCH /api/workspaces/{id} / PATCH /api/workspaces/{workspace_id}

Body

{ "name": "Arbeit Neu", "color": "#0ea5e9", "icon": "folder", "sort_order": 20 }

Response

{ "id": 2, "name": "Arbeit Neu", "color": "#0ea5e9", "icon": "folder" }

Delete

DELETE /api/workspaces/{id} / DELETE /api/workspaces/{workspace_id}

Response

{
  "deleted": 2,
  "moved_projects_to": 1,
  "moved_projects": []
}

Note: The default workspace cannot be deleted. When deleting, the user’s own projects are moved to the default workspace; todos from the workspace inbox end up in the default inbox. Display-workspace assignments for shared-project memberships are not migrated by this endpoint.

Projects

List

GET /api/projects

Response

{
  "projects": [
    {
      "id": 1,
      "name": "Inbox",
      "color": "#6366f1",
      "parent_id": null,
      "sort_order": 0,
      "is_inbox": 1,
      "is_owner": true,
      "is_shared": false
    }
  ]
}

Notes

  • Each workspace has exactly one inbox (is_inbox=1). The name may be changed; is_inbox remains the stable identity.
  • Inbox projects cannot be deleted.
  • Shared projects appear in the normal project list with is_shared=true and owner metadata.

Create

POST /api/projects

Body

{ "name": "Hobby", "color": "#ec4899", "icon": "folder", "workspace_id": 1, "sort_order": 5 }

Response

{ "id": 7, "name": "Hobby" }

Update

PATCH /api/projects/{id}

Body

{ "name": "Hobby Neu", "icon": "folder-open" }

parent_id can be set to a project ID or removed again with null:

{ "parent_id": null }

Project owners can move their own non-inbox projects to another of their workspaces:

{ "workspace_id": 2 }

When an owner moves a project, descendant projects move with it. For subtree moves the response includes an updated_projects array with the caller-specific authoritative project views so offline clients can update all affected local rows.

Shared-project members can also patch workspace_id, but only for their own display workspace. Owner moves do not change member display workspaces.

Response

{ "id": 7, "name": "Hobby Neu" }

Subtree workspace move response:

{
  "id": 7,
  "name": "Hobby Neu",
  "workspace_id": 2,
  "updated_projects": [
    { "id": 7, "name": "Hobby Neu", "workspace_id": 2 },
    { "id": 8, "name": "Child project", "parent_id": 7, "workspace_id": 2 }
  ]
}

Delete

DELETE /api/projects/{id}

The project and descendants with the same owner are deleted. Their todos are moved to the owning person’s matching inbox; for a household-owned project the household owner’s inbox is used, with a default-workspace fallback. This is not the same operation as deleting a cookbook or Shopping list, whose child content is removed.

Response

{ "deleted": 7, "deleted_ids": [7, 8] }

Delete Completed Todos in Project

POST /api/projects/{id}/clear-done / POST /api/projects/{project_id}/clear-done

Response

{ "deleted_count": 3, "deleted_ids": [17, 18, 19] }

The operation includes descendant projects owned by the caller. Accepted members can run it for projects they can access.

Project Sharing

These project-specific endpoints remain available for compatibility. V4 also exposes the generic direct-sharing API for projects, Shopping lists and cookbooks. Do not assume the two families have identical request fields or response envelopes. A household-owned entity cannot receive new direct invitations; household membership supplies its access boundary.

Fetch Shared Projects

GET /api/projects/shared

Response

{
  "projects": [
    {
      "id": 5,
      "name": "Gemeinsam",
      "member_status": "accepted",
      "member_color": "#f59e0b",
      "owner_username": "demo"
    }
  ]
}

Pending Invitations

GET /api/projects/invites

Response

{
  "invites": [
    {
      "id": 12,
      "project_id": 5,
      "project_name": "Gemeinsam",
      "project_color": "#6366f1",
      "invited_by_username": "demo",
      "invited_by_display_name": "Max Mustermann",
      "status": "pending"
    }
  ]
}

Share Project

POST /api/projects/{project_id}/share

Owner-only. username may contain a username or a verified email address. Unknown identifiers return HTTP 404. There is no read-only role: once accepted, a member can read and modify project todos and sections.

Body

{ "username": "alice" }

Response

{
  "member": {
    "id": 12,
    "project_id": 5,
    "user_id": 2,
    "username": "alice",
    "display_name": "Alice Example",
    "status": "pending"
  },
  "notification_delivery": "in_app"
}

notification_delivery is email only when mail delivery succeeds; the response still includes the resolved member object.

Accept/Decline Invitation

POST /api/projects/{project_id}/invites/{invite_id}

Body

{ "accept": true }

Response

{ "id": 12, "status": "accepted", "project_id": 5 }

List Members

GET /api/projects/{project_id}/members

Owner and accepted members may see the list. Owners see pending and accepted memberships; accepted members see accepted memberships only.

Response

{
  "members": [
    {
      "project_id": 5,
      "user_id": 2,
      "username": "alice",
      "display_name": "Alice Example",
      "status": "accepted"
    }
  ]
}

Remove Member

DELETE /api/projects/{project_id}/members/{member_user_id}

Owners can remove members, which sets status=removed; only the owner can restore that state. Members should use the dedicated leave endpoint, which sets status=left and can be undone by that member.

Response

{ "removed": 12, "project_id": 5 }

Restore Removed/Left Member

POST /api/projects/{project_id}/members/{member_user_id}/restore

Owners can restore a removed membership to accepted or pending. Restoring a left or declined recipient requires pending and fresh acceptance; an owner cannot silently re-add them. A member can only undo their own left state with accepted.

Body

{ "status": "accepted" }

Response

{ "member": { "project_id": 5, "user_id": 2, "status": "accepted" } }

Override Member Color

PATCH /api/projects/{project_id}/members/{member_user_id}/color

Owner-only. Sets a project-specific color marker for a member.

Body

{ "color": "#f59e0b" }

Response

{ "project_id": 5, "user_id": 2, "color": "#f59e0b" }

Leave Shared Project / Undo

POST /api/projects/{project_id}/leave

Owners cannot leave their own projects.

Response

{ "left": 12, "project_id": 5 }

POST /api/projects/{project_id}/leave/undo

Response

{ "member": { "project_id": 5, "user_id": 2, "status": "accepted" } }

Sections

All Sections

GET /api/sections

Response

{ "sections": [] }

Sections of a Project

GET /api/sections/by-project/{projectId} / GET /api/sections/by-project/{project_id}

Response

{
  "sections": [
    { "id": 1, "name": "Einkauf", "project_id": 2, "sort_order": 0 }
  ]
}

Create

POST /api/sections/by-project/{projectId} / POST /api/sections/by-project/{project_id}

Body

{ "name": "Einkauf", "sort_order": 0 }

Response

{ "id": 9, "name": "Einkauf" }

Update

PATCH /api/sections/{id} / PATCH /api/sections/{section_id}

Body

{ "name": "Einkauf Neu" }

Response

{ "id": 9, "name": "Einkauf Neu" }

Delete

DELETE /api/sections/{id} / DELETE /api/sections/{section_id}

Response

{ "deleted": 9 }

Accepted project members can create, update, sort, and delete sections; there is currently no read-only project role.

Reminders

List

GET /api/reminders?due_only=false

due_only=true restricts the result to due reminders. Results are user-scoped and include only todos whose status is pending or in_progress; members do not see another user’s reminder rows merely because a project is shared.

Response

{
  "reminders": [
    {
      "id": 1,
      "todo_id": 1,
      "remind_at": "2026-05-14T09:00:00",
      "sent_at": null,
      "title": "Nia einrichten",
      "status": "pending"
    }
  ]
}

Mark as Sent

POST /api/reminders/{id}/sent / POST /api/reminders/{reminder_id}/sent

Response

{ "sent": 1 }

Dashboard

Statistics

GET /api/dashboard

Response

{
  "total": 5,
  "pending": 3,
  "in_progress": 1,
  "done": 1,
  "overdue": 0,
  "due_today": 2
}

Push

Only the VAPID public-key route is public. Status, subscribe, unsubscribe, and test require user authentication.

Status

GET /api/push/status

{ "public_key": "...", "has_subscriptions": true, "subscription_count": 1 }

VAPID Key

GET /api/push/vapid-public-key

{ "public_key": "..." }

Subscribe

POST /api/push/subscribe

{ "endpoint": "https://push.example/...", "keys": { "p256dh": "...", "auth": "..." } }

Returns { "subscribed": true }.

Unsubscribe

POST /api/push/unsubscribe

The current request model requires both endpoint and keys, although only endpoint is used. Returns { "unsubscribed": true }.

Test

POST /api/push/test

Accepts optional title and body fields and returns { "sent": true } or { "sent": false }.

Public Runtime/Native Endpoints

Instance Info

GET /api/instance

Returns public instance metadata for web/native clients:

{
  "app": "nia-todo",
  "instance_id": "...",
  "display_name": "nia-todo",
  "public_base_url": "https://todo.example.com",
  "api_version": 1,
  "server_version": "4.0.0",
  "min_native_client_version": "4.0.0",
  "capabilities": ["offline-sync", "reminders", "shared-projects", "workspaces"]
}

display_name is instance-configurable and may retain the legacy default shown above. server_version follows the installed build. V4 requires native clients 4.0.0 or newer: the source floor overrides older persisted minimums, while a higher configured minimum still wins. Capability strings remain compatibility identifiers, not a complete inventory of V4 modules.

Native App Download Manifest

GET /downloads/app-downloads.json / HEAD /downloads/app-downloads.json

Returns the available Windows, Android, and Debian desktop artifacts with version, platform, architecture, filename, size, SHA256, and native-updater capability metadata. Signed Debian releases include their detached signature in the manifest. Intentionally served with no-store. If no release artifacts are published, the endpoint responds with 200 and an empty apps list so clients can hide the section cleanly without 404 console noise.

Windows Updater Manifest

GET /downloads/windows-updater.json

Projects the Windows entry from the native app download manifest into the signed Tauri updater format:

{
  "version": "3.4.0",
  "url": "https://todo.example.com/downloads/nia-todo-v3.4.0-windows-x64-setup.exe",
  "signature": "detached-updater-signature",
  "size": 12345678
}

The download URL is always constructed from the instance’s public base URL and the expected local /downloads/ path; manifest entries cannot redirect the updater to another host. The endpoint returns 204 when no signed Windows updater is available and 503 when published updater metadata is present but invalid or unreadable. Successful 200 responses are served with no-store.

GET /.well-known/assetlinks.json / HEAD /.well-known/assetlinks.json

Returns the pinned relationships delegate_permission/common.get_login_creds and delegate_permission/common.handle_all_urls between the server and bundled Android app. The manifest and asset-links routes are available only in installations that include the web directory; release packages and containers do.

OIDC / SSO

OIDC support is global/admin-configured and uses the configured public_base_url as redirect base. Provider secrets are write-only in admin responses.

Status

GET /api/oidc/status

Public status for login screens. Returns enabled and provider_name without exposing provider secrets.

User Login

GET /api/oidc/login?redirect_after=/&native=false

Starts the user OIDC authorization flow. native=true marks the flow for native app completion handoff. OIDC does not create users automatically: the provider must return a verified email matching an existing, verified local account. The authorization flow uses state, nonce, and PKCE S256.

Admin Login

GET /api/oidc/admin/login

Starts the admin OIDC authorization flow. Admin login succeeds only for an OIDC identity previously linked to the administrator account.

Callback

GET /api/oidc/callback

OIDC redirect URI. Handles user/admin/native state, exchanges the provider code, links or signs in the matching account, and returns redirect/completion HTML.

Admin Linked Identities

  • GET /api/oidc/admin/links — list linked OIDC identities for admin inspection.
  • POST /api/oidc/admin/link/start — start linking the current admin account to the configured provider.
  • DELETE /api/oidc/admin/links/{identity_id} — remove a linked OIDC identity.

Native Exchange

POST /api/oidc/native/exchange

Exchanges a short-lived, atomically single-use native completion code for the final login payload after the browser/provider flow returns to the app. The exchange endpoint itself is public.

Body

{ "code": "native-completion-code" }

Admin: OIDC Configuration

Fetch OIDC Configuration

GET /api/admin/oidc-config

Returns OIDC configuration without client_secret; secret state is exposed as client_secret_configured.

Update OIDC Configuration

PATCH /api/admin/oidc-config

Body

{
  "enabled": true,
  "provider_name": "OIDC",
  "issuer_url": "https://idp.example.com/realms/home",
  "client_id": "nia-todo",
  "client_secret": "write-only-secret",
  "public_client": false,
  "token_auth_method": "auto",
  "scopes": "openid email profile"
}

issuer_url and the computed redirect URI must use HTTPS unless loopback-only for development. token_auth_method supports auto, client_secret_basic, and client_secret_post.

Places / Location Reminders

Saved places are user-scoped helpers for location reminders. Address data stays attached to the user’s saved place and is copied to linked location reminders when a place address changes.

  • GET /api/places — list saved places.
  • POST /api/places — create a saved place with { "name": "Home", "address": "...", "icon": "home" }.
  • PATCH /api/places/{place_id} — update name, address, and/or icon.
  • DELETE /api/places/{place_id} — returns { "deleted": <place_id> }. Existing reminders keep their copied address and remain valid with place_id=null.

Todo create/update payloads may contain one user-scoped location_reminder:

{
  "trigger_type": "arrival",
  "place_id": 4,
  "enabled": true,
  "source": "explicit"
}

trigger_type (or alias trigger) must be arrival or departure. Supply either a saved place_id owned by the caller or a direct address. Coordinates and radius fields are rejected. In shared todos, each caller receives only their own location reminder. BrainDump can also return reminder candidates for saved-place names.

Admin: Sessions and Statistics

  • GET /api/admin/technical-stats — aggregate admin statistics for database growth, workload, active sessions, client mix, and provider usage counters.
  • GET /api/admin/users/{user_id}/sessions — list a user’s active device sessions.
  • DELETE /api/admin/users/{user_id}/sessions — revoke all active sessions and trusted-device credentials for a user, then bump the token version.
  • DELETE /api/admin/users/{user_id}/sessions/{session_id} — revoke one user session and its linked trusted-device credential, if present.

BrainDump Learning (Compatibility)

  • GET /api/braindump/v2/learning — returns { "enabled": true, "generation": 0, "learned_routes": 0 } for the caller.
  • PATCH /api/braindump/v2/learning with { "enabled": false } — changes the shared destination-memory switch.
  • DELETE /api/braindump/v2/learning — clears that same account’s shared destination memory and includes deleted in the response.

These BrainDump-gated endpoints are adapters to the shared destination-memory API, not an independent store. Resetting here also resets learning used by ordinary Tasks, Shopping and recipe transfers. Existing BrainDump learning is migrated into the shared system during database upgrades. Integrations that do not require BrainDump should use /api/routing-memory.

Additional Profile Endpoints

Additional profile/preferences endpoints:

  • PATCH /api/me/default-reminder — update automatic default reminder settings for todos with deadlines.
  • DELETE /api/me/avatar — remove the current avatar.

Current Route Coverage Notes

This document is intentionally example-oriented, not a generated OpenAPI specification. It is maintained against the FastAPI router inventory and the endpoint implementations, including authentication and authorization boundaries that route generation alone cannot express.

Profile / Preferences

Change Own Language

PATCH /api/me/language

Body

{ "language": "de" }

Response

{ "language": "de" }

The server normalizes pt-br to pt-BR and zh-cn to zh-CN.

Passwordless Passkey Login

These are public login endpoints for users who already have passkeys:

  • POST /api/login/passkey/options — creates a passwordless WebAuthn challenge.
  • POST /api/login/passkey/verify with { "challenge": "...", "credential": {...} } — verifies the assertion and returns the normal login response (access_token, csrf_token, user).

2FA challenge passkeys remain separate:

  • POST /api/2fa/passkey/options
  • POST /api/2fa/passkey/verify

Admin: BrainDump Configuration

Fetch BrainDump Configuration

GET /api/admin/braindump-config

Returns the stored admin configuration without secrets. Secret fields are represented as configured booleans; API keys/tokens are never echoed back.

Update BrainDump Configuration

PATCH /api/admin/braindump-config

Body

{
  "enabled": false,
  "llm_provider": "openai_compatible",
  "llm_base_url": "https://llm.example/v1",
  "llm_api_key_secret": "***",
  "llm_model": "openclaw/default",
  "llm_extra_headers_json": "{}",
  "llm_timeout_seconds": 180,
  "system_prompt_mode": "default",
  "system_prompt_custom": "",
  "stt_provider": "whisper_cpp_remote",
  "stt_url": "http://127.0.0.1:8766/inference",
  "stt_token_secret": "***",
  "stt_language": "de",
  "stt_timeout_seconds": 60
}

Supported LLM providers are openai_compatible and ollama; prompt modes are default, append, and replace. Supported STT providers are whisper_cpp_remote and local_whisper_cpp. Secrets are write-only and represented in responses by llm_api_key_configured and stt_token_configured booleans.

Test BrainDump Configuration

POST /api/admin/braindump-config/test

Probes the configured LLM model endpoint. Remote STT is exercised with synthetic WAV audio; local_whisper_cpp is reported as selected and is checked for runtime availability only during a real transcription. If BrainDump is disabled, both probes return disabled status instead of performing network calls.

Server Updates

Update Availability

GET /api/server-update

Requires normal user authentication. Returns the minimal persisted update status without starting an external release check:

{
  "update_available": true,
  "stale": false
}

update_available indicates whether the persisted stable release is newer than the running server. stale indicates that the latest external check failed or no successful check has been stored yet.

Admin: Server Updates

These endpoints support package-based self-updates for detected Debian installations. Installation requires the privileged update helper, an exactly named .deb release asset with its matching .sha256, and a newer stable version. These endpoints do not participate in the development release workflow.

  • GET /api/admin/server-update — forces a fresh external release check, then returns the current installed version, latest release status, availability and UI message.
  • GET /api/admin/server-update/progress — progress/result of a running or recently finished update process.
  • POST /api/admin/server-update/install — starts installing the latest eligible .deb update; returns process metadata or a blocked/error response.

BrainDump v2

BrainDump requires both global admin enablement and per-user access. All endpoints below require normal user authentication. The /access capability check returns HTTP 200 with { "enabled": false } when BrainDump is disabled; operational endpoints return HTTP 403.

Access

GET /api/braindump/v2/access

Response

{ "enabled": true }

Live Audio Transcription

POST /api/braindump/v2/live/audio-segment/transcribe?segment_id=1&audio_start_ms=0&audio_end_ms=4000&model=base

Request body is raw audio (webm, ogg, or another browser-provided content type). The endpoint returns transcript plus timing data and does not run LLM extraction.

Live Text Extraction

POST /api/braindump/v2/live/text-segment/extract

Body

{
  "transcript": "Milch kaufen und morgen Rechnung bezahlen",
  "segment_id": 1,
  "audio_start_ms": 0,
  "audio_end_ms": 4000,
  "supported_modules": ["tasks", "shopping"]
}

Returns segment_id, audio timestamps, transcript, normalized candidate json, its serialized raw_json, optional provider usage, and timing (llm_ms, total_ms). raw_json is serialized after normalization and learned routing, not an untouched model transcript.

supported_modules accepts tasks and/or shopping (maximum two entries). Omitting it preserves the legacy Tasks-only extraction flow. workspace_id optionally restricts the caller’s Tasks workspace context; Shopping lists are independent of Tasks workspaces. Mixed extraction returns json.candidates with module-tagged candidates for review, using bounded accessible destination context and excluding modules disabled in the account preference. Model suggestions are not writes and must not be treated as guaranteed valid target IDs. Shopping candidates use title, shopping_list_id, shopping_section_id, shopping_store_ids, quantity_value and quantity_unit. To save one, review its target and call the normal Shopping create endpoint with title mapped to name, the list ID in the URL, and shopping_section_id / shopping_store_ids mapped to section_id / store_ids. Do not forward the entire candidate unchanged: candidate routing/provenance is not a Shopping write payload. The todo-confirmation endpoint does not accept Shopping candidates.

Combined Live Audio Segment

POST /api/braindump/v2/live/audio-segment?segment_id=1&audio_start_ms=0&audio_end_ms=4000&model=base

Backward-compatible combined endpoint: transcribes one audio segment and immediately extracts candidates. It also accepts optional workspace_id and repeated supported_modules query parameters, for example supported_modules=tasks&supported_modules=shopping. Omitting modules retains Tasks-only behavior.

Create Todos from Confirmed Candidates

POST /api/braindump/v2/todos

Body

{
  "workspace_id": 1,
  "candidates": [
    {
      "module_id": "tasks",
      "client_mutation_id": "capture-laundry-1",
      "title": "Wäsche waschen",
      "notes": "",
      "project_name": "Haushalt",
      "section_name": null,
      "deadline": null,
      "reminder": null,
      "recurring_rule": null,
      "location_reminder": null
    }
  ]
}

Returns { "todos": [...] } after creating user-confirmed Tasks candidates and broadcasting normal todo create events. Candidates may include project_id, section_id, client_mutation_id and the shared routing_feedback envelope. IDs and names must resolve to destinations the caller may edit; Shopping candidates are rejected instead of silently becoming todos. Learning records confirmed choices in the same private memory used by normal Tasks writes.

Session Pipeline

  • POST /api/braindump/v2/sessions — create an in-memory BrainDump session.
  • GET /api/braindump/v2/sessions/{session_id} — fetch session state.
  • POST /api/braindump/v2/sessions/{session_id}/segments/text with { "text": "...", "final": true } — append a text segment.
  • POST /api/braindump/v2/sessions/{session_id}/finalize — finalize the session.

The session pipeline is primarily for incremental text/session state and debugging; live audio production flows use the live segment endpoints.

V4 Modules and Ownership

All endpoints in the following sections require normal user authentication, including previews and private image reads. API-key and browser-session rules above also apply. Example IDs are placeholders: obtain real IDs through an authorized list or snapshot response.

The registered module IDs are tasks, shopping and recipes. Tasks uses personal workspaces; Shopping lists and cookbooks do not belong to those workspaces. Hiding a module is an account preference, not an authorization or deletion operation.

Top-level shareable entity types are project, shopping_list and cookbook. Each has exactly one owner: a person or a household. Current accepted participants may edit content, while ownership controls management operations such as collection metadata, invitations, transfer and deletion. Children inherit the parent collection’s boundary; knowing an item, ingredient, recipe or image ID never grants access. User-specific preferences, reminders and learned routes remain private even when content is shared.

Collection responses expose owner_user_id, owner_household_id, ownership_type (user or household) and caller-specific permissions such as can_edit and can_manage. Legacy is_owner/is_shared flags are compatibility views, not a replacement for the explicit ownership fields. Household ownership is not another direct share, and personal workspaces are not households.

Account Module Preferences

  • GET /api/me/modules
  • PATCH /api/me/modules

PATCH replaces the caller’s disabled-module list:

{ "disabled_modules": ["recipes"] }

Both return the normalized { "disabled_modules": [...] } object. The preference is account-wide and synchronizes across devices; it is not scoped to a Tasks workspace. An empty list enables every registered module. At least one registered module must remain enabled; disabling all three returns HTTP 422 with detail.code = "modules.oneRequired".

The input list is limited to 128 IDs. IDs use lowercase letters, digits and hyphens, start with a letter and have at most 64 characters. Normalization removes malformed and duplicate entries while retaining valid unknown IDs for compatibility. Hiding a module preserves its data and access rights.

Create Retries and Deleted Records

Use a unique, stable client_mutation_id for each logical offline create, and reuse it only when retrying that operation. Do not generate a fresh key after a network timeout: the first write may already have committed. These keys identify creates; they are not general-purpose idempotency headers for every API mutation.

For Tasks and Shopping:

Create resource Key scope Successful replay
Todo Authenticated creation actor Current todo, subject to current access
Shopping list Authenticated creation actor Current authorized list
Shopping section, store or item Parent Shopping list and resource type Current authorized child

The server retains content-free creation receipts after deletion. Retrying a deleted create returns HTTP 410, for example:

{
  "detail": {
    "code": "sync.creationDeleted",
    "entity_type": "shopping_item",
    "id": 31,
    "shopping_list_id": 8
  }
}

shopping_list_id is included for Shopping children. A receipt does not recreate deleted content, bypass a missing parent or grant former participants access. A key collision returns the existing current object rather than applying changed input from the retry. Namespace Shopping child keys across participating clients because their scope is the shared parent list, not only the actor.

Cookbooks and recipes use their own receipts: cookbook creates replay the current authorized cookbook and return 404 when it has been deleted. Recipe mutations use revisions and applied_revision, described below. Do not treat every resource’s 404 or 410 as interchangeable.

Households

A user can own or belong to one active household; a pending membership also blocks creating or joining a conflicting household. Creating a household does not move existing personal content into it. Personal collections and accepted direct shares remain separate from household membership.

Endpoint Request Result / permission
GET /api/households/current No body { "household": null } or the caller’s current household view
GET /api/households/invites No body { "invites": [...] }, only the caller’s pending invitations
POST /api/households { "name": "Home" } { "household": {...} }; creates a household owned by the caller
PATCH /api/households/{household_id} { "name": "Our home" } { "household": {...} }; owner only
POST /api/households/{household_id}/invites { "username": "alex" } { "invite": {...}, "notification_delivery": "in_app" }; owner only
POST /api/households/{household_id}/invites/{invite_id} { "accept": true } { "id": 12, "household_id": 3, "status": "accepted" }; invited recipient only
POST /api/households/{household_id}/leave No body { "household_id": 3, "user_id": 2, "status": "left" }; non-owner member
DELETE /api/households/{household_id}/members/{member_user_id} No body { "household_id": 3, "user_id": 2, "status": "removed" }; owner only
POST /api/households/{household_id}/transfer-owner { "user_id": 2 } { "household": {...} }; owner transfers to an accepted member
DELETE /api/households/{household_id} No body { "deleted": 3, "transferred_entity_count": 4 }; owner only

Names are trimmed, required and limited to 120 characters. The invitation field is named username, but also accepts a verified email address (3–254 characters). notification_delivery is email or in_app; delivery does not accept the invitation or grant content access. accept: false declines a pending invitation. Wrong-recipient, missing and no-longer-pending invitations are not an invitation bypass.

Household views include identity/name, owner_user_id, owner display metadata, the caller’s role and members. Members see accepted memberships; the owner also sees pending memberships. A pending invite alone does not expose household content. Relationship conflicts return 409; management without ownership is rejected. The owner must transfer ownership before leaving.

Removing or leaving a household immediately removes that membership’s access to its content without deleting the content. Other genuinely independent access sources to personal entities are evaluated separately. Dissolving a household instead transfers its owned entities to the human household owner. In the current implementation dissolution clears direct entity grants and legacy project memberships on those household-owned entities; it does not preserve them as personal shares after transfer.

Transfer a Personal Collection to a Household

  • POST /api/projects/{project_id}/household with { "household_id": 3, "parent_id": null }
  • POST /api/shopping/lists/{shopping_list_id}/household with { "household_id": 3 }
  • POST /api/recipes/cookbooks/{cookbook_id}/household with { "household_id": 3 }

The caller must personally own the collection and be an accepted participant in the target household. This transfers ownership; it does not add a share. Existing direct grants are cleared. Household members receive content access through membership, and the household owner manages the entity afterward. There is no general reverse-transfer HTTP endpoint in this API reference.

Project transfer is atomic across the personal subtree, returns the caller’s root project view plus transferred_projects, and rejects inboxes or trees not entirely personally owned by the caller. An optional parent_id must refer to an accessible project owned by the target household outside that subtree. Omitted/null detaches the transferred root; descendant relationships remain. Shopping and cookbook transfers return their updated collection view and reject already household-owned collections.

Creation of projects, Shopping lists and cookbooks also accepts household_id. Omit it for personal ownership. A project parent must be compatible with its ownership boundary.

Generic Entity Sharing

Use entity_type = project | shopping_list | cookbook. These routes manage personally owned entities. Household entities return 409 for direct-sharing operations; use household membership instead. Invitations stay pending until the recipient accepts them. Pending invitations grant no content read or write access.

Endpoint Body Response
GET /api/entity-sharing/invites None { "invites": [...] }, only the caller’s pending invites
GET /api/entity-sharing/{entity_type}/{entity_id}/members None { "members": [...] }, manager only
POST /api/entity-sharing/{entity_type}/{entity_id}/invites { "identifier": "alex" } Invitation record with recipient display metadata and notification_delivery
POST /api/entity-sharing/{entity_type}/{entity_id}/invites/{invite_id} { "accept": true } Updated grant, status: "accepted" (or declined for false)
DELETE /api/entity-sharing/{entity_type}/{entity_id}/members/{member_user_id} None Updated grant, status: "removed"; manager only
POST /api/entity-sharing/{entity_type}/{entity_id}/leave None { "entity_type": "cookbook", "entity_id": 5, "left": true }
POST /api/entity-sharing/{entity_type}/{entity_id}/members/{member_user_id}/restore { "status": "accepted" } Updated grant; restoration rules below

identifier is a username or verified email address (1–320 characters). Invite-list entries include entity_type, entity_id, entity_name, entity_color, status and inviter metadata. Invitation id is the relationship ID; {member_user_id} in member routes is a user ID, not that relationship ID. Member views contain user identity/display metadata and status. Invitation/transition responses expose relationship fields such as id, entity_access_id, user_id, status, timestamps and grant/inviter IDs; clients should not assume the legacy project member envelope.

Only the entity manager may invite or remove participants. A pending invitation may only be answered by its intended recipient. The owner cannot leave their own entity. A recipient can undo their own left state with status: "accepted". The owner can restore a removed grant, but a recipient who left or declined must receive a new pending invitation (status: "pending") and accept it; the owner cannot silently re-add them. State conflicts return 409 and unauthorized restore attempts are rejected. Unknown entity types or inaccessible entity IDs return 404 rather than revealing content.

Accepted members can edit child content, but cannot manage metadata, transfer ownership, delete the collection or grant access. Sharing is additive where compatible legacy project access exists; removing one source must not be treated by a client as proof that no other source remains. Re-fetch the caller-specific snapshot after an access change.

Shopping

Shopping list, section, item and store IDs are independent of Tasks project/section IDs. Stores belong to exactly one list. Every child operation authorizes against its current parent list; sections and stores from another list cannot be assigned by passing direct IDs.

Lists and Snapshots

Endpoint Input / result
GET /api/shopping/lists { "shopping_lists": [...] }, accessible list metadata and ownership/permission fields
GET /api/shopping/lists/{shopping_list_id} One authorized list with sections, items, and caller-specific preferences
GET /api/shopping/snapshot { "shopping_lists": [...], "shopping_stores": [...] }; lists include their complete child/preference projections
POST /api/shopping/lists Create a personal or household list; returns its list view
PATCH /api/shopping/lists/{shopping_list_id} Any of name, color, icon, sort_order; manager only
DELETE /api/shopping/lists/{shopping_list_id} { "id": 8, "deleted": true }; manager only; deletes list child content
PUT /api/shopping/lists/{shopping_list_id}/preferences { "hide_empty_sections": true }; returns { "shopping_list_id": 8, "user_id": 2, "hide_empty_sections": true }

Create example:

{
  "name": "Groceries",
  "color": "#6366f1",
  "icon": "shopping-cart",
  "sort_order": 0,
  "client_mutation_id": "list-create-1"
}

household_id is optional on create. List names are trimmed, nonblank and at most 200 characters. The defaults are color: "#6366f1", icon: "shopping-cart" and sort_order: 0. client_mutation_id is optional and at most 200 characters. Omitted PATCH fields are unchanged; explicit null is invalid for sort_order. Preferences belong to the authenticated user, not every list participant; omitting hide_empty_sections in its PUT uses false.

Sections

  • POST /api/shopping/lists/{shopping_list_id}/sections with { "name": "Chilled", "sort_order": 0, "client_mutation_id": "section-create-1" }
  • PATCH /api/shopping/sections/{section_id} with name and/or sort_order
  • DELETE /api/shopping/sections/{section_id} → { "deleted": 14 }

Accepted participants may maintain sections. Names are trimmed, required and at most 200 characters. Create/update return the section record, including its id, shopping_list_id, name, sort_order and timestamps. Deleting a section keeps its items, assigning them no section. Child create keys follow the list-scoped retry contract above.

Stores

  • GET /api/shopping/stores → { "shopping_stores": [...] } for accessible lists
  • POST /api/shopping/stores with { "shopping_list_id": 8, "name": "Local shop", "sort_order": 0, "client_mutation_id": "store-create-1" }
  • PATCH /api/shopping/stores/{store_id} with name, sort_order and/or active
  • DELETE /api/shopping/stores/{store_id} — deactivates, rather than physically deleting, the store

Accepted participants may maintain stores. Names are trimmed, required and at most 120 characters. Create/update/delete return the store record, including its list ID and boolean active. Existing item relationships survive deactivation. Setting active: true restores the store; recipe transfers only accept active destination stores.

Items

  • POST /api/shopping/lists/{shopping_list_id}/items
  • PATCH /api/shopping/items/{item_id}
  • DELETE /api/shopping/items/{item_id} → { "id": 31, "shopping_list_id": 8, "deleted": true }
  • DELETE /api/shopping/lists/{shopping_list_id}/items/completed → { "shopping_list_id": 8, "deleted_ids": [31, 32] }

Create example (section and stores must belong to list 8):

{
  "name": "Milk",
  "section_id": 14,
  "quantity_value": 2.0,
  "quantity_unit": "l",
  "quantity_text": null,
  "note": "Unsweetened",
  "store_ids": [6],
  "sort_order": 0,
  "client_mutation_id": "item-create-1"
}

Create/update return the current item record. Items include numeric IDs, shopping_list_id, section, name, amount fields, quantity_display_mode, note, ordered store_ids and stores, completion metadata, timestamps and visible recipe_sources/recipe_sources_count. API writes store numeric amounts rather than preformatted display strings. Known unit aliases normalize through the shared unit registry; unknown free-form units remain supported.

Names are trimmed/nonblank and limited to 500 characters; quantity_unit to 40, quantity_text to 500, and note to 2000. Numeric quantity_value must be finite and nonnegative. Numeric and nonblank free-text quantities are mutually exclusive. For example, use quantity_text: "to taste" instead of a numeric value. Patch both fields when switching modes, clearing the old one with null. PATCH supports the create content fields plus completed and routing_feedback; omitted fields are unchanged, section_id: null clears the section, and store_ids: [] clears stores. Marking completed: true records completion time and actor; false clears them. sort_order cannot be explicitly null.

Items may carry multiple recipe-source contributions after a transfer. Source details are filtered per reader’s current recipe access: Shopping access alone does not disclose a private cookbook or its recipe details. A source contribution is provenance, not a live subscription that changes list quantities whenever the recipe changes.

Shopping-Specific Direct Sharing

These compatibility/convenience routes use the same generic entity grants for personal lists:

  • GET /api/shopping/lists/{shopping_list_id}/members → { "members": [...] }; manager only
  • POST /api/shopping/lists/{shopping_list_id}/members with { "identifier": "alex" } → pending member/invite data and notification_delivery
  • POST /api/shopping/lists/{shopping_list_id}/invites/{invite_id} with { "accept": true } → updated invitation grant
  • DELETE /api/shopping/lists/{shopping_list_id}/members/{member_user_id} → { "id": 2, "revoked": true }; manager only
  • POST /api/shopping/lists/{shopping_list_id}/leave → { "id": 8, "left": true }

Use GET /api/entity-sharing/invites to retrieve pending invitations. Household lists cannot be shared or left through these direct-sharing routes. Invitation acceptance and member IDs follow the same recipient checks and state transitions as the generic API.

Cookbooks and Recipes

Cookbooks are shareable top-level collections; recipes, groups, ingredients, steps, tags and title images inherit the cookbook’s boundary. V4 does not expose public recipe discovery, public copying or recipe archiving endpoints.

Cookbooks

Endpoint Input / result
GET /api/recipes/cookbooks { "cookbooks": [...] }; accessible books including structured recipes
GET /api/recipes/cookbooks/{cookbook_id} One authorized cookbook view
POST /api/recipes/cookbooks Create personal/household cookbook; returns its view
PATCH /api/recipes/cookbooks/{cookbook_id} Metadata update; manager only
DELETE /api/recipes/cookbooks/{cookbook_id} { "id": 5, "deleted": true }; manager only; deletes contained recipes/images

Create example:

{
  "name": "Weeknight meals",
  "description": "Recipes we make regularly",
  "color": "#6366f1",
  "icon": "book-open",
  "sort_order": 0,
  "client_mutation_id": "cookbook-create-1"
}

household_id is optional. Names must be nonblank (at most 200 characters); description is limited to 4000, create mutation ID to 1–200 characters. PATCH accepts name, description, color, icon, sort_order; explicit null is invalid for description and sort order. Cookbook views include ownership/permission metadata, recipes and recipe_count. Accepted participants can edit recipes but cannot rename or delete the cookbook. Direct sharing uses entity_type: "cookbook" in the generic sharing routes.

Recipe Aggregate

  • POST /api/recipes/cookbooks/{cookbook_id}/recipes — create a recipe in an editable cookbook
  • GET /api/recipes/recipes/{recipe_id} — read the authorized aggregate
  • PATCH /api/recipes/recipes/{recipe_id} — revision-checked aggregate update
  • DELETE /api/recipes/recipes/{recipe_id}?expected_revision=2&client_mutation_id=recipe-delete-1 — revision-checked delete

Create body:

{
  "client_mutation_id": "recipe-create-1",
  "title": "Simple rice",
  "description": "An easy side dish",
  "base_servings": 2.0,
  "prep_minutes": 5,
  "cook_minutes": 15,
  "tags": ["Vegetarian"],
  "ingredient_groups": [
    {
      "client_key": "rice-main",
      "name": "Rice",
      "ingredients": [
        {
          "client_key": "rice-dry",
          "name": "Rice",
          "quantity_value": 150.0,
          "quantity_unit": "g",
          "note": "Rinsed"
        },
        {
          "client_key": "rice-water",
          "name": "Water",
          "quantity_value": 300.0,
          "quantity_unit": "ml"
        }
      ]
    }
  ],
  "steps": [
    {
      "client_key": "rice-cook",
      "title": "Cook the rice",
      "text": "Combine the rice and water, bring to a boil and simmer until tender.",
      "ingredients": [
        { "ingredient_client_key": "rice-dry", "quantity_value": 150.0 },
        { "ingredient_client_key": "rice-water", "quantity_value": 300.0 }
      ]
    }
  ],
  "source_url": "",
  "source_name": "",
  "source_author": "",
  "source_yield": ""
}

Recipe responses contain this structured content plus server IDs/timestamps, cookbook_id, created_by_user_id, revision, can_edit, image_version and image_url. Group/ingredient/step order is array order. Server child IDs accompany stable recipe-local client_key values; keep those keys stable across edits. A recipe starts at revision 1; create/update also include the operation’s applied_revision.

Core validation:

  • title: nonblank, at most 200 characters; description: at most 4000.
  • base_servings: positive finite JSON number, at most 100000 (default 1). Times are nullable nonnegative JSON integers, at most 100000.
  • Up to 40 tags of 1–80 characters; whitespace is trimmed and duplicate names are removed case-insensitively. Tags are manual metadata, not inferred dietary guarantees.
  • Up to 50 ingredient groups, 500 ingredients in the whole recipe and 100 steps. Group names may be blank and are limited to 200 characters. Each group, ingredient and step needs a nonblank client_key of at most 200 characters, unique within its respective recipe-wide collection.
  • Ingredient names: 1–500 characters; numeric quantities: positive finite JSON numbers; unit: at most 40; alternative quantity_text: at most 500; note: at most 2000. Numeric and free-text quantities are mutually exclusive. Known units normalize through the shared registry; custom units remain valid.
  • Step title is optional (at most 200 characters), text is at most 8000; at least one must be nonblank. Title and body are separate fields; a titleless imported paragraph belongs in text.
  • Serialized aggregate input is limited to 512 KiB. Strings that are numeric substitutes for strict numeric fields are not accepted.

Step ingredient references use ingredient_client_key, never an ingredient from another recipe. Each link accepts show_quantity (default true), optional numeric quantity_value or quantity_text, and origin (manual or braindump, default manual). Numeric step quantities use the ingredient’s unit, require a numeric ingredient total and cannot exceed that total individually. show_quantity: false cannot be combined with an explicit amount. An omitted step amount does not establish that the whole total is used there; the UI may show the recipe total as context instead.

A step can also carry excluded_ingredients, an array of ingredient client keys recording explicit non-assignments. References must belong to the same recipe, be unique within the step, and cannot be both included and excluded. Backend structural validation is not a guarantee that an LLM assigned every ingredient correctly or that the sum of all step amounts equals the recipe total; review cooking allocations before saving.

Revision Conflicts and Recipe Retries

Example partial update:

{
  "client_mutation_id": "recipe-edit-1",
  "expected_revision": 1,
  "description": "Our favourite side dish",
  "cook_minutes": 18
}

client_mutation_id is required for recipe create/update/delete. Recipe IDs and positive revisions must fit a signed 64-bit integer. A successful new update increments revision. A stale expected_revision returns HTTP 409:

{
  "detail": {
    "code": "recipe.revisionConflict",
    "current": { "id": 21, "revision": 3 }
  }
}

Here current is abbreviated; the real conflict includes the full authorized current recipe. Resolve against it rather than blindly overwriting. PATCH leaves omitted fields unchanged, replaces supplied ordered arrays, and permits [] to clear them. Explicit null is invalid for title, description, base servings, tags, ingredient groups and steps; it clears nullable time/image fields. Source metadata uses empty strings to clear. When replacing ingredient groups without explicitly changing step references, inherited links to removed ingredients are pruned; explicitly supplied invalid references are rejected.

Mutation receipts are scoped to the authenticated actor and key. An exact create/update replay returns the current recipe plus the original operation’s applied_revision. These numbers can differ: a replay of a create applied at revision 1 may return a recipe now at revision 3. Reusing a key for another operation or target returns 409 recipe.mutationReused.

Delete returns { "id": 21, "cookbook_id": 5, "deleted": true, "applied_revision": 3 } and an exact delete retry can return that content-free acknowledgement after recipe deletion. The caller must still be able to edit the surviving cookbook. Replaying a create/update whose recipe has since been deleted returns 404; a receipt never resurrects it. Losing cookbook access also prevents receipt replay. These are recipe-specific contracts, not Tasks/Shopping’s HTTP 410 create tombstones.

Private Recipe Images

GET /api/recipes/recipes/{recipe_id}/image?v={image_version}

Use the image_url returned with the recipe. v is optional, at most 64 characters, and when supplied must equal the current image hash; mismatches, absent images and inaccessible recipes return 404. Reads inherit cookbook access, return raster bytes with Cache-Control: private, no-store, and vary on authentication headers/cookies. These are authenticated resources, not public image URLs.

Set image_data on a normal recipe create/PATCH to a base64 JPEG, PNG or WebP data URI; send null to remove it and omit it to leave it unchanged. Input is limited to 430000 characters / 300 KiB decoded upload bytes and 16 megapixels. The server normalizes orientation, resizes to at most 1280 pixels per edge and stores WebP with a content hash, stripping metadata. This image is stored with the recipe aggregate, independently of Tasks attachment quotas; there is no separate image-upload HTTP endpoint.

Transfer Ingredients to Shopping

POST /api/recipes/recipes/{recipe_id}/shopping-transfer

Requires read access to the recipe and content-write access to the target list. The operation is atomic and idempotent; it reads saved recipe quantities, scales them to the requested servings and writes Shopping items plus provenance in one transaction.

{
  "client_mutation_id": "recipe-transfer-1",
  "shopping_list_id": 8,
  "servings": 4.0,
  "expected_revision": 2,
  "ingredients": [
    {
      "ingredient_client_key": "rice-dry",
      "section_id": 14,
      "store_ids": [6]
    },
    {
      "ingredient_client_key": "rice-water",
      "section_id": null,
      "store_ids": []
    }
  ]
}

The ingredient selection must contain 1–500 unique recipe-local keys. Destination section/stores must belong to that target list; transfers accept only active stores. servings must be positive, finite and at most 100000. Each row optionally carries merge_group and routing_feedback.

The response includes created_count, merged_count, client_mutation_id, source_revision, and an authoritative caller-specific shopping_list projection. Counts describe insert/merge operations, not necessarily distinct final rows; several selected ingredients can contribute to one item.

Compatible numeric ingredients merge using normalized names, compatible units, note and matching section/store destinations, including existing uncompleted items. Free-text or unmeasured amounts remain separate. A request-local merge_group may explicitly combine equivalent numeric ingredients with different notes; names, units and target destinations must still agree. Notes are combined while original contributions are retained as provenance. A merge_group identifies an allowed equivalence set; it is not a universal “never merge with existing items” switch. Numeric rows can still match compatible uncompleted items. Do not assume differing recipe ingredient groups alone force separate Shopping rows.

An optional source_mutation_id identifies an already-acknowledged recipe create/update belonging to the same actor. It resolves the revision to that operation’s applied_revision, useful when an offline save was replayed before a queued transfer. In this mode expected_revision may be zero; without it a positive expected revision is required. The source must still match the resolved revision or return 409 recipe.revisionConflict; a missing/wrong source mutation returns 409 recipe.sourceMutationUnavailable.

Retry the identical transfer body/key after an uncertain response. A matching durable receipt returns the original counts and current authorized target list without applying amounts twice, even if the source recipe was edited or deleted afterward. Destination authorization is always rechecked. Reusing the key with a different request or target returns 409 recipe.transferMutationReused. Source details are not re-exposed by replay, and a receipt cannot bypass loss of target-list access.

Recipe Import and BrainDump Previews

Previews are unsaved data. They do not create a cookbook/recipe or grant access to anything. Review the draft and save it through the normal revisioned recipe API with a fresh mutation ID. External pages, recipe structure and model output can be incomplete; warning codes are advisory review information, not automatically translated prose.

Import a Recipe URL

POST /api/recipes/import-preview

{
  "url": "https://www.example.com/recipes/simple-rice",
  "include_image": true
}

Returns { "draft": {...}, "warnings": [...] } with structured recipe fields, stable draft child keys and optional normalized image_data. The draft is not a persisted record and has no saved revision. include_image defaults true and must be a JSON boolean; url is required and limited to 2048 characters. Unknown request fields are rejected.

URL import requires authentication but not BrainDump entitlement and does not call an LLM. It uses recipe-scrapers site/structured-data extraction with bounded fallbacks, not a guarantee that every recipe page or every website can be imported. Source ingredient groups are preserved when available from the supported extractor; they are not guaranteed to exist in every site’s JSON-LD. Missing quantities or serving ambiguities produce review warnings rather than invented values. Optional image failures can return a valid text draft plus recipe.import.imageUnavailable.

The server only fetches public HTTP(S) resources and revalidates redirect/DNS destinations. Private, loopback/link-local destinations, embedded credentials, unsafe URLs, oversized content and unsupported responses are rejected. Import does not execute page JavaScript, log into external accounts or scrape arbitrary local-network pages. Fetch/parse failures return HTTP 422 with detail.code in the recipe.import.* family.

BrainDump Text Import or Refinement

POST /api/recipes/ai-preview

Supply exactly one source:

{ "text": "Simple rice: serves 2. Use 150 g rice and 300 ml water. Simmer for 15 minutes." }

Or send { "draft": {...} } with recipe content for refinement: title, description, base_servings, times, tags, ingredient groups and steps, plus optional source_url, source_name, source_author, source_yield. Strip top-level IDs, permissions, revisions, client_mutation_id, image_data, image_url and image_version from an imported/saved resource first: these are not accepted draft input fields. Keep images locally while refining the content. Extra request fields are forbidden. Text is limited to 32000 characters and 128 KiB UTF-8; structured draft input is also limited to 128 KiB and validated before calling the model. There is no need to save a URL import before refining it.

Requires the existing global/per-user BrainDump access and configured shared LLM connection. Revoked BrainDump permission is checked again during and after model work; an inference already in flight cannot bypass a revocation. It does not require a second recipe-specific AI account or a separate model endpoint configuration.

Response shape:

{
  "draft": {},
  "warnings": ["recipe.ai.review"],
  "issues": []
}

The real draft contains validated recipe content. Refinement can clean descriptive marketing text, separate step titles/bodies, suggest missing group names from context and allocate ingredients/step amounts. It preserves the existing structured draft’s boundaries rather than treating arbitrary model-generated IDs as authority. Manual assignments/exclusions and source quantities constrain the result; missing/ambiguous amounts remain reviewable instead of becoming guaranteed facts. issues entries use step_client_key, code: "additional_amount_missing", ingredient_name, reason (not_listed, amount_missing or already_used) and a source evidence excerpt. They are returned only when the concrete evidence is found in the supplied source; an unsupported generic model warning is not sufficient. Review both the original amounts and per-step allocations before saving.

The operation has a bounded provider budget (at most two calls within at most 100 seconds, possibly less according to configuration), rather than unlimited retries. Refinement is not instantaneous and a successful response still needs human review. Invalid model output returns 502 recipe.ai.invalidResponse; provider failure returns 502 recipe.ai.failed; missing model configuration returns 503 recipe.ai.notConfigured; invalid input returns 422. Unavailable permission returns 403 recipe.ai.unavailable. Errors do not overwrite the caller’s draft because previews have no persistence side effect.

Preview Rate Limits

URL and BrainDump previews share a per-user admission limit of six requests per rolling minute and two concurrent provider/fetch slots per server process. HTTP 429 includes Retry-After: 60 for rate limiting or Retry-After: 5 for busy capacity, with an appropriate recipe.import.* / recipe.ai.* code. Back off instead of starting immediate retry loops. These limits are in-memory per process, not a durable cluster-wide quota.

Shared Destination Memory

  • GET /api/routing-memory — fetch the authenticated account’s state and bounded catalogs.
  • PATCH /api/routing-memory with { "enabled": false } — enable/disable learning and recall.
  • DELETE /api/routing-memory — reset the account’s learned data and return current state plus deleted.

These endpoints require authentication but do not require BrainDump. Tasks, Shopping, BrainDump candidates and recipe-to-Shopping transfers use this one private system. There is no separate per-household memory shared with other participants and no independent BrainDump database to reset.

An empty initial response is shaped as:

{
  "enabled": true,
  "generation": 0,
  "learned_routes": 0,
  "revision": 0,
  "entries": [],
  "task_entries": []
}

entries is the Shopping catalog; task_entries contains Tasks routes. Catalog entries expose a normalized name_key, key_kind, module, target and per-field confidence/evidence. Shopping routes include shopping_list_id, section_id, store_ids, list_known, section_known, stores_known and preferred; Tasks routes use project_id, workspace_id and project_known with no Shopping stores. Catalogs are bounded and filtered to destinations the caller may currently edit. An inaccessible/deleted target or inactive store must not become a usable recommendation merely because an old memory mentions it. learned_routes is a stored-entry count, not the number of confident suggestions for every phrase.

Nia uses the same learned corpus for exact, token/phrase and conservative typo recall. These are data-derived suggestions, not a fixed multilingual word database or an LLM understanding guarantee. Uncertain or conflicting evidence can deliberately yield no automatic destination. The frontend marks recalled destinations with the shared AI-icon badge and keeps them editable; explicitly chosen targets take precedence.

Teach Through Normal Writes

There is no standalone endpoint to arbitrarily insert a memory entry. Supported writes can carry explicit routing_feedback:

{
  "event_id": "user-choice-1",
  "generation": 0,
  "fields": ["list", "section", "stores"]
}

Attach this envelope to a Shopping item create/update, or to a selected ingredient in a recipe transfer. Tasks create/update and confirmed BrainDump Tasks candidates accept the same envelope, with list meaning the destination project. Fields can be module, list, section, stores; include only fields the user explicitly chose, not defaults predicted by memory. Tasks does not use stores. An empty field list deliberately avoids teaching unchanged predictions. event_id is nonblank and at most 200 characters; generation is a nonnegative JSON integer; duplicate field names normalize away.

Read the current generation before producing feedback and keep the same event identity for retries. Reset advances the generation so old offline feedback cannot recreate cleared memories. Events are deduplicated; unchanged predicted choices must not repeatedly reinforce themselves. Ordinary legacy writes and older BrainDump feedback remain supported through compatibility adapters, while new clients should send explicit feedback to distinguish manual decisions from automatic suggestions.

Disabling clears learned history, stops recall/learning and advances the generation. Re-enabling starts from the cleared state and advances the generation again. DELETE/reset also removes learned history and advances the generation, while keeping the current enabled setting; neither action deletes Tasks, Shopping items or recipes. It also affects the legacy /api/braindump/v2/learning view. Memory changes synchronize only to the owning account, and a shared entity’s other participants do not receive the account’s private routing history.

WebSocket

WEBSOCKET /ws

The client must send an authentication message within five seconds. token may contain a raw user JWT or user API key:

{ "type": "auth", "token": "..." }

A successful handshake returns { "type": "auth_ok", "user_id": 1 }; invalid or repeated authentication closes the socket with code 1008. The server permits at most ten concurrent WebSocket connections per client IP.

Supported client messages include:

  • ping → pong
  • desktop_notify_ready
  • sync_request → a caller-specific sync_response with todos, projects, sections, personal workspaces, shopping_lists, shopping_stores, cookbooks, module_preferences, household, household_invites, project_invites, shopping_invites and cookbook_invites

The server sends delta envelopes shaped as { "type": "...", "payload": {...} } for todo, subtask, comment, attachment, project, section, workspace, Shopping, sharing and preference changes. Recipes and access-boundary transitions can trigger a full authoritative sync instead of per-record deltas. Shopping snapshots include sections, items, the recipient’s list preferences and only recipe provenance that recipient may see. module_preferences_update carries { "disabled_modules": [...] }. Household and invitation data are recipient-specific: an invitation is not permission to read the entity. Clients must remove revoked content from local caches and reconcile snapshots with their own pending writes; the snapshot does not acknowledge an unsubmitted offline mutation. Dashboard synchronization sends dashboard_preferences_update with the same payload shape as GET /api/me/dashboard-preferences. The token is revalidated on sync_request, not before every pushed event. An administrator’s 2FA reset additionally sends session_invalidated and closes that user’s sockets with code 4001.

Public Web and Asset Routes

Release installations that include the web directory expose:

  • GET /, GET /setup, GET /admin, and GET /set-password — application shells
  • GET /api/avatars/{filename} — avatar files; requires user authentication
  • GET /favicon.ico / HEAD /favicon.ico
  • GET /sw.js / HEAD /sw.js
  • GET /{path:path} — SPA fallback after the explicit API and asset routes
  • static files below /static and /downloads

Backup and Restore

There is currently no HTTP API for backup or restore. Use the packaged administration tools and the operations documentation instead.

Notes

  • Each workspace has its own inbox project; callers must not assume a fixed inbox ID.
  • API keys authenticate user endpoints only, never administrator endpoints.
  • Setup write endpoints are available only during initial installation and require the one-time setup token.