Tea journaling on ATProto (alpha) forked from arabica.social/arabica
oolong docs api profile.md
3.1 kB · 83 lines
Markdown
at main

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.md and docs/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.