Users API: Profile and Preferences Endpoints in Flowtask

The Users API lets you read and update everything tied to your Flowtask account — your display name, avatar, password, and notification preferences. Profile endpoints live under /api/v1/user and require an active authenticated session (cookie-based).

All Users API endpoints require an active authenticated session. Requests without a valid session cookie receive a 401 Unauthorized response.

GET /api/v1/user/profile

Returns the full profile of the currently authenticated user. Example request

const response = await fetch('/api/v1/user/profile', {
  credentials: 'include',
});
const { user } = await response.json();

Example response

{
  "user": {
    "id": "clx0a1b2c3d4e5f6g",
    "name": "Jordan Rivera",
    "email": "jordan@example.com",
    "image": "https://cdn.flowtask.app/avatars/clx0a1b2c3d4e5f6g_abc1234",
    "isPasswordSet": true,
    "isOAuthLinked": false,
    "provider": null,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

string

Unique identifier for your account.

string | null

Your current display name, or null if not yet set.

string | null

The email address associated with your account.

string | null

URL of your avatar image, or null if no avatar has been uploaded.

boolean

true if you have a password set on your account. Accounts created via OAuth start with false.

boolean

true if your account is linked to an OAuth provider (e.g. Google).

string | null

The name of the linked OAuth provider (e.g. "google"), or null if no OAuth account is linked.

string | null

ISO 8601 datetime at which your account was created.

POST /api/v1/user/profile

Updates your display name and/or avatar image in a single request. Because this endpoint accepts a file upload, the request must use multipart/form-data encoding.

string

required

New display name. This field is required; send the current name to leave it unchanged.

file

New avatar image file (JPEG or PNG). After upload, the processed image is stored and the resulting URL is returned in the image field of subsequent profile responses.

Your uploaded avatar is stored on Flowtask’s CDN and returned as a URL in the image field. You do not need to host the image yourself. Maximum file size is 5 MB.

Example request

const form = new FormData();
form.append('name', 'Jordan Rivera');
form.append('image', fileInput.files[0]);

const response = await fetch('/api/v1/user/profile', {
  method: 'POST',
  credentials: 'include',
  body: form,
  // Do NOT set Content-Type manually — the browser sets it with the correct boundary.
});
const result = await response.json();

Example response

{
  "msg": "user profile updated successfully"
}

PUT /api/v1/user/name

Updates your display name without affecting any other profile fields.

string

required

The new display name to set for your account.

Example request

const response = await fetch('/api/v1/user/name', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Jordan Rivera' }),
});
const result = await response.json();

Example response

{
  "msg": "Name updated sucessfully to Jordan Rivera"
}

PUT /api/v1/user/password

Sets a new password or changes your existing one. If your account already has a password (isPasswordSet: true), you must supply currentPassword to authenticate the change. You must also confirm the new password by repeating it in confirmNewPassword.

string

Your current password. Required when isPasswordSet is true on your account.

string

required

The password you want to set. We recommend at least 12 characters.

string

required

Must match newPassword exactly. The request fails if the two values differ.

Example request

await fetch('/api/v1/user/password', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    currentPassword: 'hunter2',
    newPassword: 'c0rrectH0rseBatteryStaple!',
    confirmNewPassword: 'c0rrectH0rseBatteryStaple!',
  }),
});

Example response

{
  "msg": "Password updated sucessfully"
}

If your account was created via OAuth and isPasswordSet is false, you can omit currentPassword when setting a password for the first time.

GET /api/v1/user/user-preferences

Returns the notification and reminder preferences for your account. Example request

const response = await fetch('/api/v1/user/user-preferences', {
  credentials: 'include',
});
const preferences = await response.json();

Example response

{
  "emailEnabled": true,
  "reminderBefore": 30,
  "taskRemainders": true,
  "automaticRemainder": false,
  "dailyDigest": true,
  "digestTime": "08:00"
}

boolean

Whether email notifications are enabled for your account.

number

How many minutes before a task’s due time Flowtask sends a reminder.

boolean

Whether per-task reminder notifications are active.

boolean

When true, Flowtask automatically schedules reminders for newly created tasks.

boolean

Whether you receive a daily summary email of upcoming tasks.

string | null

The local time at which your daily digest is sent (e.g. "08:00"), or null if not configured.

PUT /api/v1/user/user-preferences

Updates one or more of your notification and reminder preferences. Send only the fields you want to change — unspecified fields keep their current values. At least one field must be provided.

boolean

Set to true to enable email notifications, or false to disable them.

number

Number of minutes before a task is due to send a reminder. Common values: 15, 30, 60.

boolean

Enable or disable per-task reminder notifications.

boolean

Enable or disable the daily summary email.

Example request

const response = await fetch('/api/v1/user/user-preferences', {
  method: 'PUT',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    reminderBefore: 15,
    dailyDigest: false,
  }),
});
const result = await response.json();

Example response

{
  "msg": "successfully updated the user preferences"
}

​GET /api/v1/user/profile

​POST /api/v1/user/profile

​PUT /api/v1/user/name

​PUT /api/v1/user/password

​GET /api/v1/user/user-preferences

​PUT /api/v1/user/user-preferences

GET /api/v1/user/profile

POST /api/v1/user/profile

PUT /api/v1/user/name

PUT /api/v1/user/password

GET /api/v1/user/user-preferences

PUT /api/v1/user/user-preferences