Skip to content

commitImport

POST
/imports
curl --request POST \
  --url http://localhost:8080/api/v1/imports \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --cookie hs_session=<hs_session> \
  --data '{ "pack": { "format": "homestead.circle-pack", "version": 1, "circle": { "name": "example", "icon": "example", "color": "terracotta" }, "sharedBy": { "householdName": "example", "memberName": "example" }, "people": [ { "ref": "example", "displayName": "example", "relationLabel": "example", "kind": "family", "notes": "example", "avatarUrl": "https://example.com", "accounts": [ { "platform": "instagram", "handle": "example", "platformUserId": "example", "profileUrl": "https://example.com" } ] } ], "createdAt": "2026-04-15T12:00:00Z", "expiresAt": "2026-04-15T12:00:00Z" }, "decisions": [ { "ref": "example", "action": "create", "mergeIntoPersonId": "per_01j9x3k8m2q4r5s6t7v8w9y0z1" } ], "target": { "circleId": "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
pack
required

Portable circle format. Also saved as .homestead.json files.

object
format
required
string
Allowed value: homestead.circle-pack
version
required
integer
Allowed value: 1
circle
required
object
name
required
string
icon
required
string
color
required
string
Allowed values: terracotta honey sage dusk plum clay
sharedBy
object
householdName
string
memberName
string
people
required
Array<object>
<= 1000 items
object
ref
required

Opaque per-pack reference.

string
displayName
required
string
relationLabel
string
kind
required
string
Allowed values: family friend creator other
notes
string
avatarUrl
string format: uri
accounts
required
Array<object>
object
platform
required
string
Allowed values: instagram facebook line wechat bluesky x douyin xiaohongshu truthsocial
handle
required
string
platformUserId
string
profileUrl
required
string format: uri
createdAt
required
string format: date-time
expiresAt
One of:
string format: date-time
decisions
required
Array<object>
object
ref
required
string
action
required
string
Allowed values: create merge skip
mergeIntoPersonId
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/
target
required
One of:
object
circleId
required
string
/^[a-z]{2,3}_[0-9a-hjkmnp-tv-z]{26}$/

Responses

Section titled “Responses”

200

Section titled “200”

Imported. Atomic.

Media typeapplication/json
object
circle
required
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
createdPeople
required
integer
mergedPeople
required
integer
createdAccounts
required
integer
skipped
required
integer

Examples

Exampleseed

Derived from fixtures/seed.json.

{
  "circle": {
    "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"
  },
  "createdAccounts": 1,
  "createdPeople": 1,
  "mergedPeople": 2,
  "skipped": 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"
    }
  ]
}