Skip to content

listCircles

GET
/circles
curl --request GET \
  --url http://localhost:8080/api/v1/circles \
  --cookie hs_session=<hs_session>

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”

Circles visible to the caller, in the caller’s order.

Media typeapplication/json
object
items
required
Array<object>
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
name
required
string
icon
required
string
color
required
string
Allowed values: terracotta honey sage dusk plum clay
visibility
required
string
Allowed values: household private
preset
string | null
Allowed values: family friends creators
personCount
required
integer
people

Present on getCircle only.

Array<object>
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
displayName
required
string
relationLabel
string | null
kind
required
string
Allowed values: family friend creator other
closeness
required

1 = closest. Weights the feed and hearth picks.

integer
>= 1 <= 3
avatar
One of:
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
url
required

Signed URL, valid 24 h.

string
thumbUrl
string
cardUrl
string
posterUrl
string
mime
required
string
width
integer
height
integer
durationMs
integer
blurhash
string
alt
string
inMyFeed
required
boolean
canEdit
required
boolean
sortOrder
required
integer
capturableAccounts

Accounts on platforms the extension can capture.

integer
capturableAccountLimit
integer
Allowed value: 30
lastUpdate
One of:
null

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "items": [
    {
      "canEdit": true,
      "capturableAccountLimit": 30,
      "capturableAccounts": 4,
      "color": "terracotta",
      "icon": "home",
      "id": "cir_01j9kaptqa5dcqne4nmnrbp86d",
      "inMyFeed": true,
      "lastUpdate": {
        "by": {
          "avatar": null,
          "displayName": "Mali",
          "id": "mem_01j9kt0d8rwgmhnmxkmv0frnr0"
        },
        "finishedAt": "2026-10-17T08:45:00.000Z",
        "newMoments": 4,
        "runId": "run_01j9a1b2c3d4e5f6g7h8j9k01k"
      },
      "name": "Family",
      "personCount": 4,
      "preset": "family",
      "sortOrder": 0,
      "visibility": "household"
    },
    {
      "canEdit": true,
      "capturableAccountLimit": 30,
      "capturableAccounts": 1,
      "color": "sage",
      "icon": "users-three",
      "id": "cir_01j9ebw22bbvzap1dk44j2y9eh",
      "inMyFeed": true,
      "lastUpdate": null,
      "name": "Friends",
      "personCount": 2,
      "preset": "friends",
      "sortOrder": 1,
      "visibility": "household"
    }
  ]
}