Skip to content

getStoryRail

GET
/stories
curl --request GET \
  --url 'http://localhost:8080/api/v1/stories?circleId=per_01j9x3k8m2q4r5s6t7v8w9y0z1' \
  --cookie hs_session=<hs_session>

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
circleId
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

Responses

Section titled “Responses”

200

Section titled “200”

Story rail entries in display order.

Media typeapplication/json
object
items
required
Array<object>
object
person
required
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
state
required

Visit = no fetchable content; tapping opens the suggested account.

string
Allowed values: unseen seen visit
unseenCount
required
integer
latestAt
One of:
string format: date-time
hasLiveStory
boolean
suggestedAccount
One of:
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
platform
required
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
handle
required
string
displayName
string | null
profileUrl
required
string format: uri
deepLinks
required

Client picks app link on mobile when installed, else web.

object
web
required
string format: uri
ios
string
android
string
copyValue

Value to copy when no link exists (e.g. WeChat ID).

string
hintKey

I18n key with instructions, e.g. “platformWechatOpenHint”.

string

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "items": [
    {
      "hasLiveStory": true,
      "latestAt": "2026-10-17T07:30:00.000Z",
      "person": {
        "avatar": null,
        "closeness": 1,
        "displayName": "Mom",
        "id": "per_01j9wst6a8vjc69r66y6fj70t5",
        "kind": "family",
        "relationLabel": "แม่"
      },
      "state": "unseen",
      "suggestedAccount": null,
      "unseenCount": 3
    },
    {
      "hasLiveStory": false,
      "latestAt": "2026-10-16T13:00:00.000Z",
      "person": {
        "avatar": null,
        "closeness": 2,
        "displayName": "Lin",
        "id": "per_01j9f8r1agkh6g3jp30xcwnytc",
        "kind": "family",
        "relationLabel": "Cousin"
      },
      "state": "unseen",
      "suggestedAccount": null,
      "unseenCount": 2
    },
    {
      "hasLiveStory": false,
      "latestAt": null,
      "person": {
        "avatar": null,
        "closeness": 1,
        "displayName": "Grandma Noi",
        "id": "per_01j9w5jqj9nm7gdsybfz53mcjr",
        "kind": "family",
        "relationLabel": "ยาย"
      },
      "state": "visit",
      "suggestedAccount": {
        "deepLinks": {
          "android": "https://line.me/R/ti/p/~grandma_noi",
          "ios": "https://line.me/R/ti/p/~grandma_noi",
          "web": "https://line.me/R/ti/p/~grandma_noi"
        },
        "displayName": null,
        "handle": "~grandma_noi",
        "id": "acc_01j9e81cm1p0x7vysze8aeqsje",
        "platform": "line",
        "profileUrl": "https://line.me/R/ti/p/~grandma_noi"
      },
      "unseenCount": 0
    },
    {
      "hasLiveStory": false,
      "latestAt": "2026-10-17T03:00:00.000Z",
      "person": {
        "avatar": null,
        "closeness": 3,
        "displayName": "小厨娘",
        "id": "per_01j9nt02btj9vmesaexmby3q67",
        "kind": "creator",
        "relationLabel": null
      },
      "state": "seen",
      "suggestedAccount": null,
      "unseenCount": 0
    }
  ]
}