Nia documentation · 3.2.2
API
Authenticate integrations and use the complete nia-todo API reference.nia-todo exposes a JSON API below /api. The web and native clients use the same API.
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 workspaces
- reminders and places
- sharing and invitations
- 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,
"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.
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/heicorimage/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/avatarsin Docker and/var/lib/nia-todo/avatarsin the Debian package). - DB: only
avatar_urlandavatar_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/optionsandPOST /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/optionswith{ "name": "Laptop" }— prepare registration options/challenge; allowed with enrollment-only JWT or fresh MFA reauth.POST /api/me/passkeys/verifywith{ "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/optionswith{ "challenge_token": "..." }— create an assertion challenge for an MFA login.POST /api/2fa/passkey/verifywith{ "challenge_token": "...", "credential": {...}, "remember_device": false }— complete the MFA login.POST /api/me/2fa/reauth/passkey/optionsprepares passkey reauthentication;POST /api/me/2fa/reauth/passkey/verifyaccepts{ "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_credsanddelegate_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-policyPATCH /api/admin/2fa-policywith{ "required": true }GET /api/admin/usersadditionally 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, incrementstoken_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
}
Validate Password Setup Link (public)
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"
}
Resend Expired Password Setup Link (public)
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
}
Request Password Setup Link (Admin)
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-todo",
"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-todo"
}
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
emailis 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 }
Generate Password Setup/Reset Link
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
}
Generate Password Link
POST /api/admin/users/{id}/password-link
Response
{
"password_setup_url": "https://todo.example.com/set-password?token=...",
"password_setup_expires_hours": 24
}
Set Password via Link
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_atis maintained- API keys bypass CSRF only with
Authorization: ApiKey *** Authorization: Bearer ***andX-API-Keyare not supported as API-key authentication
Todos
List
GET /api/todos
Query
status=pending|in_progress|doneproject_id=2section_id=1
Response
{
"todos": [
{
"id": 1,
"title": "Nia-Todo aufbauen",
"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-Todo aufbauen",
"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,
"location_reminder": null,
"subtasks": [
{"title": "Waschmaschine starten", "is_done": false},
{"title": "Wäsche aufhängen", "is_done": false}
]
}
Fields
titlestring, requireddescriptionstring, optionalpriorityint, optional,1..4when creating a todostatusstring, optional,pending|in_progress|doneis_pinnedbool, optionalproject_idint, optionalsection_idint, optionaldue_dateISO-8601, optional, valid year1900..9999remind_atISO-8601, optional, valid year1900..9999recurring_ruleobject, optional; supportsfrequency=daily|weekly|monthly|yearly,interval=1..999, and an optional IANA timezone other thanlocaltime. Requiresdue_date. When a recurring todo is completed, the API marks the current todo done and creates the next pending occurrence.location_reminderobject, optional; see Places and location reminders.subtasksarray, optional; checklist items withtitle,is_done, and optionalsort_order. They are lightweight checklist entries, not full child todos. REST list/get/create/update responses and WebSocket todo sync payloads includesubtasksconsistently.confirm_incomplete_subtasks_completionbool, optional; required when settingstatus=donewhile any subtask remains open.
Response
{
"id": 17,
"title": "Wäsche waschen",
"status": "pending"
}
Update
PATCH /api/todos/{id} / PATCH /api/todos/{todo_id}
Body
- same fields as POST, all optional
status=donesetscompleted_at- updating
subtasksreplaces the todo checklist with the provided ordered list - omitting
subtasksleaves the existing checklist unchanged; sending an empty array clears it - setting
status=donewhile subtasks are open returns HTTP 409 unlessconfirm_incomplete_subtasks_completion=trueis 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}/subtaskswith{ "title": "Backup prüfen", "is_done": false, "sort_order": 0 }PATCH /api/todos/{todo_id}/subtasks/{subtask_id}with any oftitle,is_done, orsort_orderDELETE /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. 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}/commentswith{ "body": "..." }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. 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 typeX-Nia-Filename(orX-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 quota of the user who uploaded the file, including in shared projects. 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_inboxremains the stable identity. - Inbox projects cannot be deleted.
- Shared projects appear in the normal project list with
is_shared=trueand 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 its descendant projects are deleted. Their todos are moved to the matching workspace inbox.
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
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 removed, left, or declined memberships to accepted or pending. A member can only undo their own left state.
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-Todo aufbauen",
"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": "3.0.2",
"min_native_client_version": "3.0.0",
"capabilities": []
}
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, and SHA256. 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.
Android Digital Asset Links
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 withplace_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
User-scoped BrainDump learning endpoints store lightweight correction preferences for future extraction.
GET /api/braindump/v2/learning— fetch the caller’s learning preferences.PATCH /api/braindump/v2/learning— update learning preferences.DELETE /api/braindump/v2/learning— clear learning preferences.
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/verifywith{ "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/optionsPOST /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.debupdate; 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
}
Returns normalized candidate JSON, raw model output, token/usage metadata when available, and timing data.
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.
Create Todos from Confirmed Candidates
POST /api/braindump/v2/todos
Body
{
"workspace_id": 1,
"candidates": [
{
"title": "Milch kaufen",
"notes": "",
"project_name": "Einkaufsliste",
"section_name": null,
"deadline": null,
"reminder": null,
"recurring_rule": null,
"location_reminder": null
}
]
}
Creates real todos from user-confirmed candidates and broadcasts normal todo create events.
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/textwith{ "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.
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→pongdesktop_notify_readysync_request→sync_responsecontaining todos, projects, sections, and workspaces
The server sends delta envelopes shaped as { "type": "...", "payload": {...} } for todo, subtask, comment, attachment, project, section, workspace, and sharing changes. 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, andGET /set-password— application shellsGET /api/avatars/{filename}— avatar files; requires user authenticationGET /favicon.ico/HEAD /favicon.icoGET /sw.js/HEAD /sw.jsGET /{path:path}— SPA fallback after the explicit API and asset routes- static files below
/staticand/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.