Skip to content

quickAdd

POST
/quick-add
curl --request POST \
  --url http://localhost:8080/api/v1/quick-add \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --cookie hs_session=<hs_session> \
  --data '{ "entries": [ { "platform": "instagram", "handle": "example", "platformUserId": "example", "profileUrl": "https://example.com", "displayName": "example", "avatarUrl": "https://example.com", "person": { "id": "per_01j9x3k8m2q4r5s6t7v8w9y0z1" }, "circleIds": [ "per_01j9x3k8m2q4r5s6t7v8w9y0z1" ] } ] }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
required
string
>= 1 characters <= 128 characters

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
entries
required
Array<object>
>= 1 items <= 100 items
object
platform
required
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
handle
required
string
platformUserId
string
profileUrl
string format: uri
displayName
string
avatarUrl
string format: uri
person
required
One of:
object
id
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
circleIds
Array<string>

Responses

Section titled “Responses”

200

Section titled “200”

People and accounts created or attached. Atomic.

Media typeapplication/json
object
people
required
Array
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
accounts
required
Array
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
personId
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
platformUserId
string | null
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
fetchTier
required
string
Allowed values: server agent closed
status
required
string
Allowed values: pending ok stale needs_agent login_required not_found error paused closed
statusDetailKey
string | null
fetchIntervalS
integer | null
lastSuccessAt
One of:
string format: date-time
nextFetchAt
One of:
string format: date-time
createdAt
required
string format: date-time
circleIds
required
Array<string>
notes
string | null
lastVisitedAt
One of:
string format: date-time
latestMomentAt
One of:
string format: date-time
snoozedUntil
One of:
string format: date-time
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
deletedAt
One of:
string format: date-time
createdPeople
required
integer
createdAccounts
required
integer
skipped
required
Array<object>
object
index
required
integer
code
required
string
Allowed values: already_exists invalid_handle platform_unsupported
existingAccountId
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "createdAccounts": 2,
  "createdPeople": 1,
  "people": [
    {
      "accounts": [
        {
          "avatar": null,
          "createdAt": "2026-09-17T09:00:00.000Z",
          "deepLinks": {
            "android": "https://x.com/nok_travels",
            "ios": "https://x.com/nok_travels",
            "web": "https://x.com/nok_travels"
          },
          "displayName": null,
          "fetchIntervalS": 10800,
          "fetchTier": "agent",
          "handle": "nok_travels",
          "id": "acc_01j9a1b2c3d4e5f6g7h8j9k00b",
          "lastSuccessAt": null,
          "nextFetchAt": null,
          "personId": "per_01j9a1b2c3d4e5f6g7h8j9k00a",
          "platform": "x",
          "platformUserId": null,
          "profileUrl": "https://x.com/nok_travels",
          "status": "pending",
          "statusDetailKey": null
        },
        {
          "avatar": null,
          "createdAt": "2026-09-17T09:00:00.000Z",
          "deepLinks": {
            "android": "https://bsky.app/profile/nok.bsky.social",
            "ios": "https://bsky.app/profile/nok.bsky.social",
            "web": "https://bsky.app/profile/nok.bsky.social"
          },
          "displayName": null,
          "fetchIntervalS": 3600,
          "fetchTier": "server",
          "handle": "nok.bsky.social",
          "id": "acc_01j9a1b2c3d4e5f6g7h8j9k00c",
          "lastSuccessAt": null,
          "nextFetchAt": null,
          "personId": "per_01j9a1b2c3d4e5f6g7h8j9k00a",
          "platform": "bluesky",
          "platformUserId": null,
          "profileUrl": "https://bsky.app/profile/nok.bsky.social",
          "status": "pending",
          "statusDetailKey": null
        }
      ],
      "avatar": null,
      "circleIds": [
        "cir_01j9ebw22bbvzap1dk44j2y9eh"
      ],
      "closeness": 2,
      "createdAt": "2026-10-17T09:00:00.000Z",
      "deletedAt": null,
      "displayName": "Nok",
      "id": "per_01j9a1b2c3d4e5f6g7h8j9k00a",
      "kind": "friend",
      "lastVisitedAt": null,
      "latestMomentAt": null,
      "notes": null,
      "relationLabel": null,
      "snoozedUntil": null,
      "updatedAt": "2026-10-17T09:00:00.000Z"
    },
    {
      "accounts": [
        {
          "avatar": null,
          "createdAt": "2026-09-17T09:00:00.000Z",
          "deepLinks": {
            "android": "https://www.instagram.com/_u/lin.cooks/",
            "ios": "instagram://user?username=lin.cooks",
            "web": "https://www.instagram.com/lin.cooks/"
          },
          "displayName": null,
          "fetchIntervalS": 10800,
          "fetchTier": "agent",
          "handle": "lin.cooks",
          "id": "acc_01j9te0skfktnnmw6zvew46azb",
          "lastSuccessAt": "2026-10-17T08:00:00.000Z",
          "nextFetchAt": null,
          "personId": "per_01j9f8r1agkh6g3jp30xcwnytc",
          "platform": "instagram",
          "platformUserId": null,
          "profileUrl": "https://www.instagram.com/lin.cooks/",
          "status": "ok",
          "statusDetailKey": null
        }
      ],
      "avatar": null,
      "circleIds": [
        "cir_01j9kaptqa5dcqne4nmnrbp86d"
      ],
      "closeness": 2,
      "createdAt": "2026-09-17T09:00:00.000Z",
      "deletedAt": null,
      "displayName": "Lin",
      "id": "per_01j9f8r1agkh6g3jp30xcwnytc",
      "kind": "family",
      "lastVisitedAt": null,
      "latestMomentAt": "2026-10-17T06:00:00.000Z",
      "notes": null,
      "relationLabel": "Cousin",
      "snoozedUntil": null,
      "updatedAt": "2026-09-17T09:00:00.000Z"
    }
  ],
  "skipped": [
    {
      "code": "already_exists",
      "existingAccountId": "acc_01j9te0skfktnnmw6zvew46azb",
      "index": 1
    }
  ]
}

400

Section titled “400”

Invalid request.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}

409

Section titled “409”

Conflicts with current state.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required
string
i18nKey
string
detail
string
fields
Array<object>
object
path
required
string
code
required
string
i18nKey
string

Example generated

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "code": "example",
  "i18nKey": "example",
  "detail": "example",
  "fields": [
    {
      "path": "example",
      "code": "example",
      "i18nKey": "example"
    }
  ]
}