Skip to content

Update a user's profile

PATCH
/users/{ref}

Updates a person’s profile and returns it.

You need to be signed in. To edit your own profile you need profile.update_self or system.admin; to edit someone else’s you need users.profile.edit.any or system.admin; grants within a team don’t count. A ref that isn’t a whole number, or a body that isn’t valid JSON for these fields, gets a plain-text 400 before sign-in is checked.

When you edit your own profile, the operator’s self-edit settings apply, to administrators too: sending a value for display_name, bio, avatar_url, location or website_url while that field is locked rejects the whole request with 422, naming the first locked one in that order, even if the value wouldn’t change. Edits to someone else’s profile skip these settings. The settings are checked before the account is looked up; an unknown ref then gets 404.

Fields you leave out or send as null keep their values; any other value is saved as sent, and only theme is checked. The profile is read, merged and written back whole with no version check, so two edits at the same time can undo each other’s changes.

Editing your own profile also records a profile update for federation, in the same step as the save; an edit of someone else’s doesn’t. After each successful save, even one that changes nothing, the server tries to add an audit entry; if that fails, the edit still succeeds. Server errors get a plain-text 500.

ref
required
integer format: int64

The account’s ref.

Fields to change. A field that’s missing or null keeps its value; any other value replaces it, so an empty string clears a text field. For avatar_url and website_url an empty string saves an empty address, and neither can go back to unset. The length limits and the website format shown aren’t checked.

object
display_name

The name to show. An empty string clears it, and the profile then shows the fallback name described under display_name in the response.

string
nullable <= 100 characters
bio
string
<= 1000 characters
avatar_url

The address of the profile picture, saved as given; nothing is uploaded, fetched or checked.

string
nullable <= 1024 characters
location
string
<= 100 characters
website_url

The website address, saved as given; its format isn’t checked.

string format: uri
nullable <= 500 characters
social_links

The whole set of links, replacing the saved set: {} clears it, and a key sent with null is saved with an empty value.

object
key
additional properties
string
<= 100 characters
language

Your language preference, such as en or es-AR; an empty string clears it. Any text is accepted.

string
<= 35 characters
theme

light, dark or system, which follows each device’s setting, or an empty string to clear the preference so each device uses the app default. Anything else gets 400.

string
Allowed values: "" light dark system
hide_from_anonymous

true hides your profile from visitors who aren’t signed in: both public profile routes answer them 404, as if there were no such account. Signed-in callers still see it, and it doesn’t change who can see your posts or other work. The profile doesn’t report this setting back.

boolean

The profile as read back after the edit.

A person’s profile. Which names are included depends on whether you’re signed in; see display_name and fullname.

object
ref
required
integer format: int64
username
required

The account’s username; an empty string if it has none.

string
fullname

The account’s full name. Sent only to signed-in callers, and only when it isn’t empty; profile edits don’t change it.

string
nullable
display_name
required

The name to show, never empty: the profile’s display name, then the account’s full name, then the username, and as a last resort user followed by the account number. For readers who aren’t signed in, the full name is skipped.

string
bio

An empty string when none is set.

string
avatar_url

The stored picture address; the server doesn’t upload, fetch or check it. Left out when unset; clearing it through this API returns an empty string.

string
nullable
location

An empty string when none is set.

string
website_url

The website address as saved; its format isn’t checked. Left out when unset; clearing it through this API returns an empty string.

string format: uri
nullable
social_links

Platform names mapped to handles or links stored in the profile; nothing is checked. Left out when there are none.

object
key
additional properties
string
language

The owner’s language preference as saved, meant to be a tag such as en or es-AR; the server doesn’t check it. Left out when not set.

string
theme

The owner’s theme preference: light, dark or system, which follows each device’s setting. Left out when not set.

string
Allowed values: "" light dark system
member_since
required

When the account was created.

string format: date-time
post_count
required

How many published posts the person has that aren’t deleted. Every one counts, including posts you can’t open, so it can be higher than what you can see.

integer format: int64
origin_server_id

The server a copied profile came from. Left out for this server’s own users; nothing in the API creates copies.

string format: uuid
nullable

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

A field you sent is locked for self-editing; field names the first one, and nothing was saved.

object
error
required
string
reason
required
string
Allowed values: field_disabled_by_operator
field
required
string