PassDown API

Reference v1.0

PassDown API

A REST API for building on top of PassDown. All endpoints are versioned, use bearer authentication, and return JSON.

Base URL: https://api.passdown.app

Auth: Bearer token

Rate limit: 120 req/min

Authentication

Every request must include a bearer token issued from the PassDown dashboard.

Authorization: Bearer pd_live_1a2b3c…

Heirlooms

GET/v1/heirlooms

List heirlooms in the current family, with filters and pagination.

Example

curl https://api.passdown.app/v1/heirlooms?category=Jewelry \
  -H "Authorization: Bearer $TOKEN"

POST/v1/heirlooms

Create a new heirloom entry.

Example

curl -X POST https://api.passdown.app/v1/heirlooms \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "title": "Grandmother's Locket", "category": "Jewelry" }'

PATCH/v1/heirlooms/:id

Update fields on an existing heirloom.

Example

curl -X PATCH https://api.passdown.app/v1/heirlooms/h1 \
  -d '{ "status": "reserved" }'

DELETE/v1/heirlooms/:id

Delete a heirloom and its associated interests and memories.

Example

curl -X DELETE https://api.passdown.app/v1/heirlooms/h1

Interests

GET/v1/interests

List interests visible to the current user.

Example

curl https://api.passdown.app/v1/interests

POST/v1/heirlooms/:id/interests

Express interest in a heirloom.

Example

curl -X POST https://api.passdown.app/v1/heirlooms/h1/interests \
  -d '{ "message": "This piece is precious to me." }'

PATCH/v1/interests/:id

Approve or decline an interest (steward only).

Example

curl -X PATCH https://api.passdown.app/v1/interests/i1 \
  -d '{ "status": "approved" }'

Memories

GET/v1/heirlooms/:id/memories

List all memories attached to a heirloom.

Example

curl https://api.passdown.app/v1/heirlooms/h1/memories

POST/v1/heirlooms/:id/memories

Add a memory to a heirloom.

Example

curl -X POST https://api.passdown.app/v1/heirlooms/h1/memories \
  -d '{ "body": "Dad wound it every Sunday." }'

Distributions

POST/v1/heirlooms/:id/finalize

Finalize a distribution (executor only).

Example

curl -X POST https://api.passdown.app/v1/heirlooms/h1/finalize

GET/v1/distributions/ledger

Export the immutable distribution ledger for your family.

Example

curl https://api.passdown.app/v1/distributions/ledger

Webhooks

Subscribe to events to keep your systems in sync.

heirloom.created

heirloom.updated

interest.created

interest.approved

distribution.finalized

memory.added