Share a circle

Sharing a circle lets your brother, a friend or anyone else add the same people to their own Homestead. A share carries names and public profile links only, never posts or stories. See Circles and sharing for what’s included.

In the app

Available on main (W-07)

1. Open the circle and select Share.

2. Choose when the link expires: 1 day, 7 days, 30 days, 1 year or never. The default is 7 days if the circle has family in it, 30 days otherwise.

3. Decide whether to include relation labels (“Mom”, “ยาย”) and include notes. Both are off by default.

4. Read the privacy line: “Anyone with this link can see the names and profile links in this circle. No posts or stories are shared.”

5. Create the link. You get a QR code, a copy button, and on phones the system share sheet. The link is shown only once.

Existing links are listed with their view and import counts and a Revoke button.

With the API, for now

The server side is on main, so until the screen lands you can share with curl, a member device token (see Use your X API key for how to get one), or an agent with the shares:write scope (the homestead_share_circle tool).

1. Find the circle’s ID.

   curl http://localhost:8080/api/v1/circles -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN"

2. Create the share. expiresInDays is 1, 7, 30, 365 or null for never; leave it out for the default.

   curl -X POST http://localhost:8080/api/v1/circles/cir_YOUR_CIRCLE_ID/shares -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN" -H "Content-Type: application/json" -d '{"expiresInDays":30,"includeRelationLabels":false,"includeNotes":false}'

   The reply’s url is the link to send. It looks like https://home.example.com/s/… and uses your HOMESTEAD_BASE_URL.

3. To revoke it later, use the share’s id.

   curl -X DELETE http://localhost:8080/api/v1/shares/shr_YOUR_SHARE_ID -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN"

Opening an expired or revoked link gives share_expired or share_revoked.

Import a shared circle

In the app

Available on main (W-07)

The public page for a link shows the circle, who shared it, and the people. Import into my Homestead asks for your Homestead’s address and takes you to its import screen. There each person gets a suggested action (Create, Merge into someone you have, or Skip) and you pick a target circle. Download circle file saves a .homestead.json file instead.

With the API

Preview first. Give either the link as url, or the contents of a .homestead.json file as pack:

curl -X POST http://localhost:8080/api/v1/imports/preview -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN" -H "Content-Type: application/json" -d '{"url":"https://home.example.com/s/SHARE_TOKEN"}'

The reply has the pack and a matches list with a suggestedAction for each person’s ref. Then commit with your decisions, a target circle and an Idempotency-Key:

curl -X POST http://localhost:8080/api/v1/imports -H "Authorization: Bearer hsd_YOUR_DEVICE_TOKEN" -H "Content-Type: application/json" -H "Idempotency-Key: import-family-1" -d @import.json

where import.json holds {"pack": …, "decisions": [{"ref": "…", "action": "create"}], "target": {"newCircle": {"name": "Family"}}}.

Importing by link needs a public address

Your Homestead fetches the link from the other server, and it refuses private, local and CGNAT addresses. A share from a Homestead that’s only on a home network or Tailscale can’t be imported by link. Use the .homestead.json file instead; you can get it from GET /api/v1/public/shares/{token} on the sharing server.

Check that it worked

• The share’s view and import counts go up (GET /api/v1/circles/{circleId}/shares).
• On the importing side, the people appear in the target circle.