friendship

Friendship Tracker

A personal contact book API. Manage contacts plus their notes, activities, and reminders - everything tied back to a single contact via parent_id. Built for solo users keeping a Monica-style CRM.

Base URL

https://friendship-tracker.com

Three ways to connect to Friendship Tracker - same data, same access rules, different path depending on the job.

HTTP API

For your own apps, server-to-server integrations, webhooks. Full control, any language.

CLI

For CI, scripts, bulk imports, quick terminal probing. One line to install.

MCP

For AI assistants like Claude or Cursor that should work with your data directly.

Usage & billing

Fair API usage within the published rate limits is included on every plan - the integration shouldn't feel artificially constrained just because you're on a smaller tier. Enterprise customers get bespoke limits on request.

On-demand service is available, and our developer team builds custom integrations on request - reach out if your use case needs more than the standard hookup.

Quick start

1
Create a token
Open the Integrations menu in Friendship Tracker, click *New token*, pick a name + scopes, and copy the pat_… secret. It's shown exactly once.
2
Make your first request
Pass the token as a Bearer header to any Friendship Tracker endpoint your scopes allow. Pagination, filtering, and sorting are documented per model.
```
curl -H "Authorization: Bearer pat_…" \
     https://friendship-tracker.com/xapi2/data/activity
```

Subscribe to live updates

Open a single WebSocket and receive every create / update / delete event in real time - same access rules, same token. Skip polling entirely.

const ws = new WebSocket(`wss://${location.host}/xapi2/ch?token=${token}`)
ws.onopen = () => ws.send(
  JSON.stringify({ op: "subscribe", id: "s1", dataType: "activity" }),
)
ws.onmessage = (e) => console.log(JSON.parse(e.data))

Navigate

These docs cover every endpoint the app exposes. Each model page carries concrete code samples in curl, JavaScript, TypeScript, and WebSocket.

Authentication

JWT vs PAT, Bearer header.

WebSocket transport

Live events + CRUD over one socket.

Error envelope

Uniform error responses.

Rate limits

Per IP and per token.

Explore data models

11 data models available.

Command line (CLI)

Native client for every endpoint - one line to install.

MCP for AI clients

Plug Claude, Cursor & friends into your data.

Client libraries

Drop-in API wrappers for Python, TypeScript, Go, Java, Rust.

Outgoing webhooks

React to data changes in real time.

Data models

Production-grade, industry-standard data models. Every object is managed securely - validation, access rules, and audit run uniformly on every path - and the data is owned by the respective customer at all times. Export and deletion are first-class.

Arrows point from the referencing data model to the referenced one. Endpoint markers describe cardinality (e.g. * = any number, 1 = exactly one, 0..1 = optional). Click a node to open its model page.

Required referenceOptional reference

Activities

activity

A logged interaction with a contact (meeting, call, email, message, event, other). Bound to a contact via parent_id, optionally carries occurred_at and location.

6 fields→ 1 refs

GETGETPOSTPATCHDELETE

Contacts

contact

A person you keep in touch with. Carries identity (name, nickname, email, phone), context (company, address, social links), and lifecycle fields (birthday, anniversary, last_contacted_at). Acts as the parent for notes, activities, and reminders.

29 fields← 10

GETGETPOSTPATCHDELETE

Conversations

conversation

Lightweight communication log: a single call / sms / video / in-person check-in. Logging one bumps the parent contact's last_contacted_at via the bump_last_contacted hook, so the stay-in-touch dashboard updates automatically.

7 fields→ 1 refs

GETGETPOSTPATCHDELETE

Custom fields

custom_field

Arbitrary label/value attached to a contact. kind picks the FE renderer (text / number / date / url / bool); only the textual value is stored on the wire.

5 fields→ 1 refs

GETGETPOSTPATCHDELETE

Gifts

gift

A gift idea, given, or received - bound to a contact. Status drives the lane (Idea / Given / Received).

9 fields→ 1 refs

GETGETPOSTPATCHDELETE

Journal

journal_entry

A standalone diary entry, not tied to any contact. Mood + tag the entry and skim it from the journal page.

5 fields

GETGETPOSTPATCHDELETE

Life events

life_event

Significant moments in a contact's life - birthdays, anniversaries, job changes, moves, milestones. Recurring flags year-on-year events for the dashboard.

7 fields→ 1 refs

GETGETPOSTPATCHDELETE

Notes

note

A free-form journal entry attached to a contact via parent_id. Multiple notes per contact, ordered chronologically. Supports a pinned flag.

3 fields→ 1 refs

GETGETPOSTPATCHDELETE

Pets

pet

An animal companion of the contact. Top-N species enum (dog/cat/bird/...) plus species_other for exotic cases. Optional breed, born_at, colour, notes.

8 fields→ 1 refs

GETGETPOSTPATCHDELETE

Relationships

relationship

A directional link between two owned contacts. The pair_relationship after_create hook mirrors each row on the target contact so both detail pages see the link.

6 fields→ 2 refs

GETGETPOSTPATCHDELETE

Reminders

reminder

A one-shot follow-up tied to a contact: a due_date, a message, and a completed boolean. Recurrence is intentionally out of scope.

4 fields→ 1 refs

GETGETPOSTPATCHDELETE