Skip to main content
Update User
Updates one or more profile fields for the specified user. A user edits only their own profile. A service key edits a user by acting as that user: it must send actingUserId naming the user in the path, and the request then behaves exactly as that user’s own token would. Supports direct image uploads for the avatar and banner via multipart/form-data. Uploaded images are processed, stored in Supabase, and the old files are automatically cleaned up after a successful update.
Send application/json for text-only updates. Use multipart/form-data when uploading image files.

Authentication

Requires a user access token whose user matches :userId, or a service key that sends actingUserId set to :userId.

Path Parameters

string
required
The Sublay user ID (UUID) to update.

Body Parameters

string
Service key only, and required with one: the user this request acts as. It must be the user in the path (:userId). Not an update field. A user token always acts as its own user and must not send it (400 user/acting-user-not-allowed). With multipart/form-data, send it as a form field.
All other fields are optional. Only the fields provided are updated.
string
Display name.
string
New username. Automatically lowercased and sanitized. Returns 409 if already taken by another user.
string
URL of the user’s avatar image. Ignored if avatarFile is also provided.
string
Short bio text.
string
ISO 8601 datetime string for the user’s date of birth (e.g. "1990-06-15T00:00:00.000Z").
object
Geographic location stored as a PostGIS point.
object
Public custom key-value data. Replaces the existing value.
object
Custom key-value data. No API response returns it, to this user or anyone else; your backend receives it in webhooks. The user can write it themselves, so don’t store anything your app needs to trust here. Replaces the existing value.
file
Avatar image file (multipart). Maximum 50 MB. Must be a valid image. Requires avatarFile.options to be present in the same request.
file
Banner image file (multipart). Maximum 50 MB. Must be a valid image. Requires bannerFile.options to be present in the same request.

Response

On success, returns HTTP 200 with the updated user’s authenticated profile:
string
Unique user ID (UUID).
string | null
External identifier from your system.
string
User role (e.g., "visitor").
string | null
User’s email address.
string | null
Updated display name.
string | null
Updated username.
string | null
Avatar URL.
string | null
Bio text.
object | null
Public custom key-value data.
number | null
Reputation score.
boolean | null
Whether the user’s email has been verified.
boolean | null
Whether the user account is active.
string | null
ISO timestamp of the user’s last activity.
array
Active suspensions on the account.
object | null
Processed avatar image with variants.
object | null
Processed banner image with variants.
string[]
Active auth methods (e.g., ["password", "google"]).
string
ISO timestamp of account creation.
When name, username, or bio changes, the user’s semantic search embedding is automatically updated asynchronously.

Error Responses

Returned with no JSON body: 401 when no Authorization header is sent, 403 when the access token is invalid or expired. Checked before any uploaded file is read, so a request with no credentials gets 401 rather than a body or acting-user error. A valid token for a different user gets 403 user/not-authorized instead (Signed In as Another User, below).
A valid user token, signed in as a user other than :userId, tried to update that user. Returned with a JSON body, unlike the invalid-token 403 above.
The user in the path no longer exists, for example a user token that outlived its user.
A service key sent no actingUserId.
A service key sent an actingUserId other than :userId.
A user token sent actingUserId, even naming its own user. Only a service key names the user it acts as; a user token always acts as its own user.
Returned when a service key names an actingUserId that isn’t a user in this project, so also when it names a :userId that doesn’t exist.
Returned when an avatar or banner is uploaded on a project without the files-images bundle.

See Also