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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”The account’s ref.
Request Body required
Section titled “Request Body required ”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
The name to show. An empty string clears it, and the profile then shows the fallback name described under display_name in the response.
The address of the profile picture, saved as given; nothing is uploaded, fetched or checked.
The website address, saved as given; its format isn’t checked.
The whole set of links, replacing the saved set: {} clears it, and a key sent with null is saved with an empty value.
object
Your language preference, such as en or es-AR; an empty string
clears it. Any text is accepted.
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.
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.
Responses
Section titled “ Responses ”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
The account’s username; an empty string if it has none.
The account’s full name. Sent only to signed-in callers, and only when it isn’t empty; profile edits don’t change it.
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.
An empty string when none is set.
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.
An empty string when none is set.
The website address as saved; its format isn’t checked. Left out when unset; clearing it through this API returns an empty string.
Platform names mapped to handles or links stored in the profile; nothing is checked. Left out when there are none.
object
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.
The owner’s theme preference: light, dark or system, which
follows each device’s setting. Left out when not set.
When the account was created.
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.
The server a copied profile came from. Left out for this server’s own users; nothing in the API creates copies.
Malformed request
object
Human-readable error summary
Example
the request could not be completedAuthentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Authenticated but missing required capabilities
object
Human-readable error summary
Example
the request could not be completedResource not found
object
Human-readable error summary
Example
the request could not be completedA field you sent is locked for self-editing; field names the first
one, and nothing was saved.