Public profile by stable ref (used by notifications + cross-refs)

GET

/users/by-ref/{ref}

• Local development behind nginx (port 8088 by default)

Same public profile as /users/by-username, resolved by the stable user ref (#478, ADR 0070). Distinct from GET /users/{ref} (authenticated internal read) so the anonymous public surface is a separate, narrowly-scoped path. Public-mode + opt-out semantics identical to the by-username variant.

Parameters

Path Parameters

ref

required

integer format: int64

Responses

200

Public profile

Merged user + profile view. display_name is the resolved display string, first non-empty of:

authenticated: profile.display_name → user.fullname → username anonymous: profile.display_name → username

The anonymous ladder skips fullname, and has since #478 — real name is authenticated-only (ADR 0070 §3), so a fallback that reached it would defeat that rule silently, for exactly the users who never set a display name. This sentence used to describe only the authenticated ladder, which made the schema the stale source; the rule itself is one Go expression (users.ResolveDisplayName), shared with PostAuthor.

avatar_url is null for users without an uploaded avatar; the frontend renders a generated initials disc in that case.

object

ref

required

integer format: int64

username

required

string

fullname

The raw user.fullname value, for the rare case a caller needs the unresolved string (account settings page). Most UI surfaces should use display_name instead.

string

nullable

display_name

required

Resolved display string ready to render — never empty.

string

bio

string

avatar_url

string

nullable

location

string

website_url

string format: uri

nullable

social_links

Free-form platform → handle map. Frontend renders known platforms (twitter, instagram, artstation, …) as icon links; unknown keys are ignored.

object

key

additional properties

string

language

IETF BCP47 language tag (e.g. “en”, “es-AR”). Empty string = “use system / browser default”. Drives the i18n switcher in the user menu.

string

theme

UI theme preference. system follows the OS; empty string = no stored preference. Persisted alongside the profile so it follows the user across browsers (#677).

string

Allowed values: "" light dark system

member_since

required

string format: date-time

post_count

required

Total live posts authored by this user.

integer format: int64

origin_server_id

Set on profiles mirroring a remote site’s user. NULL = locally-owned account.

string format: uuid

nullable

401

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"
}

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed