User

These endpoints manage the authenticated user’s own profile, display preferences, and account. For data export/import, see Import & Export. For API tokens, see API Tokens.

All endpoints require authentication and operate only on the authenticated user’s own account.

Profile

Get current user profile

GET /api/user/profile

curl https://your-instance.example.com/api/user/profile \
  -H "Authorization: Bearer ntag_xxx"

{
  "user": {
    "id": "clxuser1",
    "email": "ada@example.com",
    "name": "Ada",
    "surname": "Lovelace",
    "theme": "DARK",
    "dateFormat": "MDY",
    "language": "en",
    "graphMode": "individuals",
    "emailVerified": true
  }
}

Update user profile

PUT /api/user/profile

Field	Type	Notes
name	string	Required, 1-100 characters.
surname	string or null
nickname	string or null
email	string	Required, valid email.

If email changes, a verification email is sent and the account is marked unverified until confirmed. Returns 409 with code email_in_use if another account already uses that email.

curl -X PUT https://your-instance.example.com/api/user/profile \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Ada", "surname": "Lovelace", "email": "ada@example.com" }'

{ "user": { "id": "clxuser1", "email": "ada@example.com" }, "emailChanged": false }

Password

Change password

PUT /api/user/password

Field	Type	Notes
currentPassword	string	Required.
newPassword	string	Required. Min 8 characters, must include uppercase, lowercase, a number, and a special character.

curl -X PUT https://your-instance.example.com/api/user/password \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "currentPassword": "OldPass1!", "newPassword": "NewPass2@" }'

{ "message": "Password updated" }

A successful change signs out every session: all web sessions issued before the change are rejected and all device sessions (native app tokens) are deleted, including the one used for this request. Sign in again with the new password.

Preferences

Each preference has its own small PUT endpoint. All return a user object containing the account id and the preference that changed, and nothing else (except language, see below). They deliberately do not return the full profile: use GET /api/user/profile when you need that.

{ "user": { "id": "clxuser1", "theme": "DARK" } }

Update theme

PUT /api/user/theme

Body: { "theme": "LIGHT" | "DARK" }

curl -X PUT https://your-instance.example.com/api/user/theme \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "theme": "DARK" }'

Update date format

PUT /api/user/date-format

Body: { "dateFormat": "MDY" | "DMY" | "YMD" }

Update name display order

PUT /api/user/name-order

Body: { "nameOrder": "WESTERN" | "EASTERN" }

Update name display format

PUT /api/user/name-display-format

Body: { "nameDisplayFormat": "FULL" | "NICKNAME_PREFERRED" | "SHORT" }

Update network-graph display mode

PUT /api/user/graph-display

Body: { "graphMode": "individuals" | "bubbles" }

curl -X PUT https://your-instance.example.com/api/user/graph-display \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "graphMode": "bubbles" }'

Update address geocoding preference

PUT /api/user/geocoding

Body: { "geocodingEnabled": true }. Re-enabling queues previously skipped addresses for the background geocoder.

{ "user": { "id": "clxuser1", "geocodingEnabled": true } }

Update reminder lead time

PUT /api/user/reminder-lead-days

Body: { "days": 7 }. Integer from 0 to 365. This sets how many days before an important date its advance-notice reminder email should fire. A value of 0 means day-of only: the day-of reminder still fires, but no separate advance-notice email is sent. The advance-notice reminder is always in addition to the day-of reminder, it never replaces it. Applies to every important date that has not set its own lead time override.

curl -X PUT https://your-instance.example.com/api/user/reminder-lead-days \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "days": 7 }'

{ "user": { "id": "clxuser1", "defaultReminderLeadDays": 7 } }

Update weekly digest preferences

PUT /api/user/weekly-digest

Field	Type	Notes
enabled	boolean	Required. The weekly digest is opt-in and off by default.
weekday	integer	Required, 0 to 6, where 0 is Sunday and 6 is Saturday.

The two fields are saved together because a weekday is meaningless without the toggle. When enabled, a weekly email summarizing upcoming events is sent on the chosen weekday. If there are no upcoming events that week, no email is sent.

curl -X PUT https://your-instance.example.com/api/user/weekly-digest \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "weekday": 1 }'

{ "user": { "id": "clxuser1", "weeklyDigestEnabled": true, "weeklyDigestWeekday": 1 } }

Update language

PUT /api/user/language

Body: { "language": "en" | "es-ES" | "ja-JP" | "nb-NO" | "de-DE" | "fr-FR" }

curl -X PUT https://your-instance.example.com/api/user/language \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "language": "es-ES" }'

{ "success": true, "language": "es-ES" }

Photo

Upload or replace user photo

POST /api/user/photo

multipart/form-data with a photo field. Cropped to 256x256, converted to JPEG, EXIF stripped. Returns 400 with code photo_missing if no photo field is sent, and 413 with code photo_too_large (params.maxBytes) if the file exceeds 50 MB.

curl -X POST https://your-instance.example.com/api/user/photo \
  -H "Authorization: Bearer ntag_xxx" \
  -F "photo=@ada.jpg"

{ "photo": "clxuser1-a1b2c3.jpg" }

Remove user photo

DELETE /api/user/photo

curl -X DELETE https://your-instance.example.com/api/user/photo \
  -H "Authorization: Bearer ntag_xxx"

{ "message": "Photo deleted" }

Get current user photo

GET /api/photos/user

curl https://your-instance.example.com/api/photos/user \
  -H "Authorization: Bearer ntag_xxx" \
  -o me.jpg

Like person photos, the response has an ETag and answers 304 Not Modified to a matching If-None-Match.

Account deletion

DELETE /api/user/delete

Permanently deletes the account and all associated data. This cannot be undone.

Field	Type	Notes
password	string	Required for credential-based accounts (not OAuth/OIDC).
confirmationText	string	Required, must be exactly "DELETE".

curl -X DELETE https://your-instance.example.com/api/user/delete \
  -H "Authorization: Bearer ntag_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "password": "CurrentPass1!", "confirmationText": "DELETE" }'

{ "message": "Account deleted" }