Profile API #
GET /api/profile/{actor} #
Returns a user's public oolong profile bundle: identity, their records across
the five active entity collections, and the steep count per tea. The
/profile/{actor} page route answers this same body when it negotiates JSON,
through the same loader, so both apply the same moderation filtering.
Path parameters #
| Param | Description |
|---|---|
actor |
The profile owner's DID (did:plc:...) or handle. |
Request #
No parameters. The response depends on the viewer only through
is_own_profile; the endpoint is public.
This endpoint never redirects: the JSON body always carries the canonical
handle in profile.handle. The page route does redirect /profile/{did} to
/profile/{handle} through the Solid shell's metadata, once the bundle
resolves.
Response #
{
"did": "did:plc:abc123",
"profile": {
"handle": "alice.test",
"display_name": "Alice",
"avatar": "https://cdn.bsky.app/..."
},
"is_own_profile": false,
"brews": [Brew],
"teas": [Tea],
"vendors": [Vendor],
"vessels": [Vessel],
"infusers": [Infuser],
"brew_count_by_tea": {"3kabc": 4}
}
| Field | Type | Description |
|---|---|---|
did |
string |
The profile owner's DID. |
profile |
object |
handle, display_name, avatar (empty strings when unset). |
is_own_profile |
bool |
True when the viewer owns the profile. |
brews |
Brew[] |
Steeps, with tea/vessel_obj/infuser_obj joined by rkey. |
teas |
Tea[] |
Teas, with vendor joined by rkey. |
vendors |
Vendor[] |
Vendors. |
vessels |
Vessel[] |
Vessels. |
infusers |
Infuser[] |
Infusers. |
brew_count_by_tea |
{tea_rkey: int} |
Steeps logged per tea, across the returned brews. |
Collections are always arrays ([], never null) and brew_count_by_tea is
always an object ({} when empty).
Errors #
| Status | Code | When |
|---|---|---|
| 400 | invalid_request |
Empty actor. |
| 404 | not_found |
Actor cannot be resolved, is blacklisted, or has published no oolong records and is not a registered user. |
| 502 | service_unavailable |
Resolving the actor or reading their collections failed upstream (PDS unreachable, non-404 XRPC error). |
| 500 | internal_error |
Unexpected local failure. |
Blacklisted actors answer exactly like unknown actors, so moderation state does not leak.
Visibility #
- Records hidden by moderation are removed from every collection before the response is built, so the page cannot show what this endpoint omits.
- No aggregate stat (average rating, vendor stats) is exposed here, so the
profile stats-visibility preference has nothing to leak on this endpoint. It is
enforced on the entity and backlinks endpoints instead — see
docs/api/settings.mdanddocs/api/entities.md. - A failed collection read is reported as an error rather than as an empty
collection. Only a genuinely missing actor, or a registered user with no
records, produces
404 not_found.