# jiajun.fyi APIs

> The APIs behind jiajun.fyi: one person's library, English practice, recipes and commute tools, with what an agent can call and how.

Use this file to find which service and endpoint fit a task, then read that service's own documentation (linked below) before calling it. Do not guess endpoints, fields or scopes.

## Agent workflow

1. Pick the service from the list below. Prefer the library's public API (pih-api.jiajun.fyi): it is the stable interface, and it reads videos as time-stamped timelines.
2. Only call services marked `Callable with an API key` or `Public`. A `Login only` service is behind the owner's Cloudflare Access login: say so and stop; do not try to get around it.
3. Read the key from the `PIH_API_KEY` environment variable (or `~/.personal-info-hub/pih.env`) and send `Authorization: Bearer pih_...`. Never ask the user to paste it into chat or put it in browser code. Without one, run `pih login --scopes <the scopes the task needs>`: the owner approves the printed link and the key lands in that file.
4. Fetch the service's llms.txt or OpenAPI when it has one, then call it.
5. Answer with sources: the item's hubUrl, and timestamps for video. Write (collect, star, note) only when asked.
6. A service that collects links and processes them later should not poll: ask the owner for its own key plus a callback webhook, and act on `item.ready` (see the public API's llms.txt).

Nothing any key can reach deletes data, except with the admin scope, which is for the owner's own tools.

## Services

### Personal Info Hub · public API (pih-api.jiajun.fyi)

Search and read everything the owner collected (articles, posts, video transcripts as timelines, media); collect links, star, add notes. The stable interface for agents. Services that collect links get signed callback webhooks (item.collected / item.ready / item.failed) instead of polling.

- Access: Callable with an API key
- Auth: Authorization: Bearer pih_... (scoped key)
- llms.txt: https://pih-api.jiajun.fyi/llms.txt
- OpenAPI: https://pih-api.jiajun.fyi/openapi.json
- Reference: https://pih-api.jiajun.fyi/docs

#### Endpoints

- GET https://pih-api.jiajun.fyi/search: Search the library (search:read)
- GET https://pih-api.jiajun.fyi/items: List items (items:read)
- GET https://pih-api.jiajun.fyi/shots: Videos laid out as shots (切片) (items:read)
- GET https://pih-api.jiajun.fyi/items/{id}: Get one item (items:read)
- GET https://pih-api.jiajun.fyi/items/{id}/content: Get an item's content (items:read)
- GET https://pih-api.jiajun.fyi/items/{id}/media/{mediaId}: Download one media file by its stable address (media:read)
- GET https://pih-api.jiajun.fyi/items/{id}/timeline: Read a video or episode as a timeline (items:read)
- PUT https://pih-api.jiajun.fyi/items/{id}/note: Set an item's note (notes:write)
- POST https://pih-api.jiajun.fyi/items/{id}/star: Star or unstar an item (notes:write)
- POST https://pih-api.jiajun.fyi/items/{id}/later: Mark or clear read / watch later (notes:write)
- POST https://pih-api.jiajun.fyi/collect: Collect a link (collect:write)
- POST https://pih-api.jiajun.fyi/flomo/memos: Write a memo to Flomo (notes:write)
- GET https://pih-api.jiajun.fyi/english/words: List English words (english:read)
- GET https://pih-api.jiajun.fyi/english/practice: List English practice records (english:read)
- GET https://pih-api.jiajun.fyi/songbook/songs: List songbook songs with their links (songbook:read)
- POST https://pih-api.jiajun.fyi/songbook/songs: Add a song to the songbook (songbook:write)
- POST https://pih-api.jiajun.fyi/songbook/score-takes: Save a recording and its detected notes (songbook:write)
- GET https://pih-api.jiajun.fyi/songbook/score-takes: List 扒谱结果 (takes saved from 实时扒谱) (songbook:read)
- GET https://pih-api.jiajun.fyi/songbook/score-takes/{id}: Read one 扒谱结果 with its MusicXML and lyrics (songbook:read)
- POST https://pih-api.jiajun.fyi/songbook/links/match: Match a batch of songbook links (songbook:write)
- PATCH https://pih-api.jiajun.fyi/songbook/songs/{key}/links/{service}: Set a song's link by hand (songbook:write)
- GET https://pih-api.jiajun.fyi/songbook/tracklists: List tracklists (songbook:read)
- POST https://pih-api.jiajun.fyi/songbook/tracklists: Ask for a 1001Tracklists set (songbook:write)
- GET https://pih-api.jiajun.fyi/songbook/tracklists/{id}: Read one tracklist (songbook:read)
- POST https://pih-api.jiajun.fyi/songbook/tracklists/{id}/reread: Read a stored set page again (songbook:write)
- GET https://pih-api.jiajun.fyi/songbook/sheets: List 图图乐谱 sheets (songbook:read)
- PATCH https://pih-api.jiajun.fyi/songbook/sheets/{key}: Change a song's 图图乐谱 sheet (songbook:write)
- POST https://pih-api.jiajun.fyi/things/wanted: Record something the owner wants to buy (记到想买) (things:write)
- GET https://pih-api.jiajun.fyi/things/products: Search 物品 (products) (things:read)
- GET https://pih-api.jiajun.fyi/things/wanted-webhook: Read the 想买 Webhook address (things:write)
- POST https://pih-api.jiajun.fyi/things/wanted-webhook: Make a new 想买 Webhook address (things:write)
- GET https://pih-api.jiajun.fyi/things/wanted.shortcut: Download the signed 记到想买 Shortcut (things:write)
- GET https://pih-api.jiajun.fyi/restaurants: Search 餐厅 (restaurants) (restaurants:read)
- POST https://pih-api.jiajun.fyi/restaurants: Add a restaurant (or find it) (restaurants:write)
- GET https://pih-api.jiajun.fyi/restaurants/{id}: Read one restaurant (restaurants:read)
- PATCH https://pih-api.jiajun.fyi/restaurants/{id}: Change a restaurant (restaurants:write)
- POST https://pih-api.jiajun.fyi/restaurants/{id}/visits: Record a visit (去吃了) (restaurants:write)
- POST https://pih-api.jiajun.fyi/restaurants/{id}/links: Link two stores (关联的店) (restaurants:write)
- PATCH https://pih-api.jiajun.fyi/restaurants/{id}/links/{linkId}: Confirm or remove a link (restaurants:write)
- GET https://pih-api.jiajun.fyi/restaurants/{id}/reviews: Read a restaurant's reviews (评价) (restaurants:read)
- PATCH https://pih-api.jiajun.fyi/restaurants/{id}/reviews: Pin or settle a review listing (restaurants:write)
- POST https://pih-api.jiajun.fyi/restaurants/{id}/reviews/refresh: Fetch a restaurant's reviews again (restaurants:write)
- GET https://pih-api.jiajun.fyi/books: List 读书 (WeRead books) (books:read)
- GET https://pih-api.jiajun.fyi/books/highlights: Search highlights and thoughts (划线、想法) (books:read)
- GET https://pih-api.jiajun.fyi/books/stats: Read 阅读时长 (reading time) (books:read)
- GET https://pih-api.jiajun.fyi/books/{id}: Read one book's notes (books:read)
- POST https://pih-api.jiajun.fyi/books/sync: Sync WeRead now (立即同步) (books:write)
- GET https://pih-api.jiajun.fyi/people: List 人物 (people) (people:read)
- POST https://pih-api.jiajun.fyi/people: Add a person (or find them) (people:write)
- GET https://pih-api.jiajun.fyi/people/{id}: Read one person and their items (people:read)
- PATCH https://pih-api.jiajun.fyi/people/{id}: Rename a person, or change aliases or description (people:write)
- POST https://pih-api.jiajun.fyi/people/{id}/merge: Merge two records of the same person (people:write)
- POST https://pih-api.jiajun.fyi/people/{id}/items: Link an item to a person (people:write)
- PATCH https://pih-api.jiajun.fyi/people/{id}/items/{itemId}: Change or remove a person's item (people:write)
- GET https://pih-api.jiajun.fyi/recipes: List 菜谱 (recipes) (recipes:read)
- POST https://pih-api.jiajun.fyi/recipes: Write your own recipe version for a saved post (recipes:write)
- GET https://pih-api.jiajun.fyi/recipes/{id}: Read one recipe (recipes:read)
- GET https://pih-api.jiajun.fyi/recipes/{id}/versions: List every version of a dish (recipes:read)
- PUT https://pih-api.jiajun.fyi/recipes/{id}/want: Mark 想做 (want to cook), or take it back (recipes:write)
- POST https://pih-api.jiajun.fyi/recipes/{id}/cooked: Log a 做过 (cooked it) (recipes:write)
- POST https://pih-api.jiajun.fyi/recipes/{id}/plan: Plan the dish for a day (排餐), or take it off (recipes:write)
- POST https://pih-api.jiajun.fyi/recipes/grocery: Add a line to the grocery list (采购清单) (recipes:write)
- POST https://pih-api.jiajun.fyi/recipes/import: Turn saved posts or videos into recipes (recipes:write)
- POST https://pih-api.jiajun.fyi/feedback: Report a problem, a missing capability or an idea (any key)
- GET https://pih-api.jiajun.fyi/feedback: List agent feedback (feedback:read)
- GET https://pih-api.jiajun.fyi/feedback/{id}: Read one report (by id or FB-12) with its logs and calls (feedback:read)
- PATCH https://pih-api.jiajun.fyi/feedback/{id}: Sort, resolve or merge a report (by id or FB-12) (feedback:read)
- GET https://pih-api.jiajun.fyi/todos: List 待办 (todos) (todos:read)
- POST https://pih-api.jiajun.fyi/todos: Add a todo (todos:write)
- PATCH https://pih-api.jiajun.fyi/todos/{id}: Change a todo, complete, drop or reopen it (todos:write)
- GET https://pih-api.jiajun.fyi/card-notes: List 卡片笔记 (card notes), newest first (card_notes:read)
- POST https://pih-api.jiajun.fyi/card-notes: Add a card note (card_notes:write)
- GET https://pih-api.jiajun.fyi/card-notes/tags: List the tags in the card box, with counts (card_notes:read)
- GET https://pih-api.jiajun.fyi/card-notes/{id}: Read one card note (card_notes:read)
- PATCH https://pih-api.jiajun.fyi/card-notes/{id}: Change a card note, or take it back (撤销) (card_notes:write)
- GET https://pih-api.jiajun.fyi/tutu/media: List 图图's photos and videos (tutu:read)
- GET https://pih-api.jiajun.fyi/tutu/media/{id}: Get one of 图图's photos or videos (tutu:read)
- GET https://pih-api.jiajun.fyi/tutu/days: List 图图's daycare days: arrival, pick-up and naps (tutu:read)
- PUT https://pih-api.jiajun.fyi/tutu/push-device: Turn new-photo notifications on or off for one device (tutu:read)
- GET https://pih-api.jiajun.fyi/tutu/home-logs: List 图图's home logs: sleep, wake-up, meals, poops, photos (tutu:read)
- POST https://pih-api.jiajun.fyi/tutu/home-logs: Log something at home: fell asleep, woke up, a meal, a poop, a photo (tutu:write)
- GET https://pih-api.jiajun.fyi/tutu/home-logs/{id}: Get one home log (tutu:read)
- PATCH https://pih-api.jiajun.fyi/tutu/home-logs/{id}: Change a home log, or take it back (撤销) (tutu:write)
- POST https://pih-api.jiajun.fyi/tutu/home-logs/{id}/photos: Add a photo to a home log (tutu:write)
- GET https://pih-api.jiajun.fyi/tutu/growth: List 图图's growth measurements (tutu:read)
- POST https://pih-api.jiajun.fyi/tutu/growth: Add a growth measurement (health:write)
- GET https://pih-api.jiajun.fyi/tutu/growth/chart: 图图's growth chart with WHO bands (tutu:read)
- GET https://pih-api.jiajun.fyi/tutu/health/records: List 图图's health records (health:read)
- POST https://pih-api.jiajun.fyi/tutu/health/records: Add a health record (health:write)
- GET https://pih-api.jiajun.fyi/tutu/health/records/{id}: Get one health record (health:read)
- PATCH https://pih-api.jiajun.fyi/tutu/health/records/{id}: Change a health record (health:write)
- GET https://pih-api.jiajun.fyi/tutu/health/vaccines: 图图's vaccines (health:read)
- GET https://pih-api.jiajun.fyi/connectors: How each 同步源 (sync) stands (items:read)
- POST https://pih-api.jiajun.fyi/notify: Tell the owner something (notify:write)
- POST https://pih-api.jiajun.fyi/tikhub: Make one TikHub request through the hub (tikhub:call)
- POST https://pih-api.jiajun.fyi/renders: Render a Blender scene (queued) (renders:write)
- GET https://pih-api.jiajun.fyi/renders/{id}: Read a render: status and progress (renders:read)
- GET https://pih-api.jiajun.fyi/renders/{id}/frames: List a render's frames (renders:read)
- GET https://pih-api.jiajun.fyi/renders/{id}/frames/{name}: Read one frame (renders:read)

#### Callback webhooks

Sent to an HTTPS endpoint the owner registers for your key; see llms.txt「Service callers」.

- EVENT https://pih-api.jiajun.fyiitem.collected: Item collected: fetched, still processing (signed (Standard Webhooks))
- EVENT https://pih-api.jiajun.fyiitem.ready: Item ready: all processing done (signed (Standard Webhooks))
- EVENT https://pih-api.jiajun.fyiitem.failed: Item failed, with reason (signed (Standard Webhooks))
- EVENT https://pih-api.jiajun.fyiwebhook.test: Test event (signed (Standard Webhooks))

### Personal Info Hub · internal API (api.hub.jiajun.fyi)

The /api used by the hub web app, the Chrome extension, the pih CLI and MCP. Callable with a scoped key; not a stable contract, so prefer the public API when it covers the task.

- Access: Callable with an API key
- Auth: Authorization: Bearer pih_... with the scope in each row; every DELETE and any unlisted route needs admin
- Stability: internal, may change without notice

#### Items

- GET https://api.hub.jiajun.fyi/api/items: Item cards, newest first; with q it searches (items:read (search:read with q))
- POST https://api.hub.jiajun.fyi/api/items: Collect a URL (collect:write)
- GET https://api.hub.jiajun.fyi/api/items/facets: Counts for the sidebar filters (items:read)
- GET https://api.hub.jiajun.fyi/api/items/tags: Top tags (items:read)
- GET https://api.hub.jiajun.fyi/api/stats/collected: Items collected per Pacific day and source (?days=30|90) (admin)
- GET https://api.hub.jiajun.fyi/api/items/{id}: Full item detail (the hub item page) (items:read)
- POST https://api.hub.jiajun.fyi/api/items/{id}/star: Star or unstar (notes:write)
- GET https://api.hub.jiajun.fyi/api/items/{id}/status: Processing stages (items:read)
- GET https://api.hub.jiajun.fyi/api/items/{id}/media: Media rehost status (items:read)
- GET https://api.hub.jiajun.fyi/api/media/{id}: A stored media file (Range supported) (items:read)
- GET https://api.hub.jiajun.fyi/api/x-bookmarks/search: Search X bookmarks (search:read)
- POST https://api.hub.jiajun.fyi/api/integrations/flomo/memos: Write a memo to Flomo (notes:write)

#### Processing

- POST https://api.hub.jiajun.fyi/api/items/{id}/media: Queue a media rehost (sync:write)
- POST https://api.hub.jiajun.fyi/api/items/{id}/refetch: Fetch the item again (sync:write)
- POST https://api.hub.jiajun.fyi/api/items/{id}/replies: Expand comment replies (paid TikHub calls) (sync:write)
- POST https://api.hub.jiajun.fyi/api/items/{id}/transcribe: Queue a Whisper transcription (sync:write)
- POST https://api.hub.jiajun.fyi/api/items/{id}/reprocess: Run processing again (sync:write)

#### Collectors and sync

For the owner's own sync clients (extension, pih CLI, hercules jobs).

- POST https://api.hub.jiajun.fyi/api/import/{source}: Bulk import: browser-bookmarks, x-bookmarks, youtube-saved-videos, bilibili-favorites, instagram-saved-items, xiaohongshu-favorites, xiaohongshu-liked-items (sync:write)
- GET https://api.hub.jiajun.fyi/api/source-connectors: List sync sources (sync:write)
- POST https://api.hub.jiajun.fyi/api/source-connectors: Create or update a sync source (sync:write)
- POST https://api.hub.jiajun.fyi/api/source-connectors/{id}/{action}: sync-result, boost, pause, resume, retry, trigger (sync:write)
- POST https://api.hub.jiajun.fyi/api/recordings: Recorded list responses (X bookmarks, Xiaohongshu): store, read, import (sync:write)
- GET https://api.hub.jiajun.fyi/api/extension/scrapers/{name}: Extension page recorder source (sync:write)
- GET https://api.hub.jiajun.fyi/api/brightwheel/fetch-plan: Brightwheel fetch plan (sync:write)
- POST https://api.hub.jiajun.fyi/api/brightwheel/import-batch: Brightwheel import (sync:write)
- POST https://api.hub.jiajun.fyi/api/brightwheel/captures: Brightwheel captures (sync:write)
- GET https://api.hub.jiajun.fyi/api/storage/objects: List or read private objects (key or prefix) (sync:write)
- PUT https://api.hub.jiajun.fyi/api/storage/objects: Write a private object if absent (never overwrites or deletes); with uploadId&partNumber, one part of a multipart upload (sync:write)
- POST https://api.hub.jiajun.fyi/api/storage/objects: Multipart upload for files over 100 MiB: ?uploads starts, ?uploadId completes (or &abort) (sync:write)
- POST https://api.hub.jiajun.fyi/api/watch-history/items: Report watched titles (Emby) (sync:write)
- POST https://api.hub.jiajun.fyi/api/watch-history/events: Report watch sessions (sync:write)
- GET https://api.hub.jiajun.fyi/api/watch-history/watched: What counts as watched (sync:write)
- PUT https://api.hub.jiajun.fyi/api/watch-history/items/{id}/captions: Upload a title's subtitles (sync:write)
- PUT https://api.hub.jiajun.fyi/api/watch-history/items/{id}/audio: Upload a title's audio for transcription (sync:write)
- POST https://api.hub.jiajun.fyi/api/cue-clips/plan: Plan sentence clips for studied words (sync:write)
- POST https://api.hub.jiajun.fyi/api/video-stills/plan: Queue a video still for every timed recipe step without one (?item= for one item) (admin)
- GET https://api.hub.jiajun.fyi/api/cue-clips/queue: Clips waiting to be cut (sync:write)
- PUT https://api.hub.jiajun.fyi/api/cue-clips/{id}/file: Upload a cut clip (sync:write)
- POST https://api.hub.jiajun.fyi/api/cue-clips/{id}/failed: Mark a clip failed (sync:write)
- POST https://api.hub.jiajun.fyi/api/jobs/claim: Claim this Mac's most urgent queued jobs (video_rehost, upgrade_video), leased (sync:write)
- POST https://api.hub.jiajun.fyi/api/jobs/{id}/heartbeat: Renew a claimed job's lease, with its progress (sync:write)
- POST https://api.hub.jiajun.fyi/api/jobs/release: Give claimed jobs back untouched (sync:write)
- GET https://api.hub.jiajun.fyi/api/jobs/overview: Jobs queue: backlog by status, runner and type; failures; attention; quotas (admin)
- GET https://api.hub.jiajun.fyi/api/jobs: One group of jobs (status, runner, type, error prefix) (admin)
- POST https://api.hub.jiajun.fyi/api/jobs/{id}/retry: Run a job again now (admin)
- POST https://api.hub.jiajun.fyi/api/jobs/{id}/cancel: Call a job off (admin)
- POST https://api.hub.jiajun.fyi/api/jobs/bulk: Retry or close a whole failure group (admin)
- POST https://api.hub.jiajun.fyi/api/items/{id}/video-rehost: Register a rehosted video (sync:write)
- POST https://api.hub.jiajun.fyi/api/items/{id}/captions/punctuate: Punctuate machine captions (sync:write)
- GET https://api.hub.jiajun.fyi/api/captions/readable-pending: Captions waiting for punctuation (sync:write)

#### Photo prints (冲印)

Which photos were printed. The Google Photos extension uses its own key; tutu.jiajun.fyi goes through its Access login.

- GET https://api.hub.jiajun.fyi/api/photo-prints: 待冲印, 待确认 and every print batch with its photos (photo_prints:read)
- POST https://api.hub.jiajun.fyi/api/photo-prints: Add photos to 待冲印 ({photos: [{mediaKey | publicId, takenAt?, thumbUrl?}]}); status unconfirmed for an album import (photo_prints:write)
- POST https://api.hub.jiajun.fyi/api/photo-prints/status: Was each photo printed or waiting? (by media key, short id or taken time) (photo_prints:read)
- POST https://api.hub.jiajun.fyi/api/photo-prints/batches: Record a print batch: date, vendor, size for the chosen photos (photo_prints:write)
- PATCH https://api.hub.jiajun.fyi/api/photo-prints/{id}: Move a 待确认 photo to 待冲印 (photo_prints:write)

#### Restaurants (餐厅)

The same record as the public API's /restaurants; agents use that one. Deletes are admin only.

- GET https://api.hub.jiajun.fyi/api/restaurants: List restaurants (?q=&status=want|been&area=&cuisine=&links=unconfirmed|review) (restaurants:read)
- GET https://api.hub.jiajun.fyi/api/restaurants/{id}: One restaurant with its linked stores and visits (restaurants:read)
- POST https://api.hub.jiajun.fyi/api/restaurants: Add a restaurant, or find the one already there (same name + place) and fill in what it lacked; another place is another store, linked to the same-name ones (restaurants:write)
- PATCH https://api.hub.jiajun.fyi/api/restaurants/{id}: Change fields (restaurants:write)
- POST https://api.hub.jiajun.fyi/api/restaurants/{id}/visits: Record a visit; the restaurant becomes 去过 (restaurants:write)
- POST https://api.hub.jiajun.fyi/api/restaurants/{id}/links: Link another store (关联的店, 已确认) (restaurants:write)
- PATCH https://api.hub.jiajun.fyi/api/restaurants/{id}/links/{linkId}: Confirm a link, mark it 待清洗, or remove it (restaurants:write)
- DELETE https://api.hub.jiajun.fyi/api/restaurants/{id}: Remove a restaurant recorded by mistake, with its visits, links and reviews (admin)
- DELETE https://api.hub.jiajun.fyi/api/restaurants/visits/{id}: Remove one visit (admin)

#### Books (读书)

WeRead (微信读书), synced read-only by the API; the same record as the public API's /books. Private books need ?includePrivate=true. The key is set on jiajun.fyi/admin/settings (管理 → 设置 → 微信读书).

- GET https://api.hub.jiajun.fyi/api/books: Books (?status=reading|finished|unread|all&q=&includePrivate=&cursor=&limit=), with counts and sync state (books:read)
- GET https://api.hub.jiajun.fyi/api/books/{id}: One book: highlights by chapter, thoughts under them, reviews (books:read)
- GET https://api.hub.jiajun.fyi/api/books/highlights: Search highlights and thoughts (?q=&bookId=) (books:read)
- GET https://api.hub.jiajun.fyi/api/books/stats: Reading time (?range=week|month|year|total) (books:read)
- POST https://api.hub.jiajun.fyi/api/books/sync: Sync WeRead now (立即同步) (books:write)
- GET https://api.hub.jiajun.fyi/api/settings/weread: Key status (last four characters only), sync state, counts (admin)
- PUT https://api.hub.jiajun.fyi/api/settings/weread: Save the wrk- key (encrypted) and test it (admin)
- POST https://api.hub.jiajun.fyi/api/settings/weread/test: Test the saved key (admin)
- DELETE https://api.hub.jiajun.fyi/api/settings/weread: Remove the key (admin)

#### People (人物)

People from the library (interview guests, hosts, authors, subjects) with their items; the same record as the public API's /people. New items are read by 人物识别 after their summary.

- GET https://api.hub.jiajun.fyi/api/people: People, most items first (?q=&role=&cursor=&limit=) (people:read)
- GET https://api.hub.jiajun.fyi/api/people/{id}: One person with their items (people:read)
- POST https://api.hub.jiajun.fyi/api/people: Add, or find the one already there by name or alias (people:write)
- PATCH https://api.hub.jiajun.fyi/api/people/{id}: Rename, aliases, description, link (people:write)
- POST https://api.hub.jiajun.fyi/api/people/{id}/merge: Fold another person into this one ({personId}) (people:write)
- POST https://api.hub.jiajun.fyi/api/people/{id}/items: Link an item ({itemId, role}) (people:write)
- PATCH https://api.hub.jiajun.fyi/api/people/{id}/items/{itemId}: Change the role, or remove the link ({removed: true}) (people:write)
- POST https://api.hub.jiajun.fyi/api/people/detections: Import the backfill's detections (scripts/people-backfill.mjs) (admin)
- DELETE https://api.hub.jiajun.fyi/api/people/{id}: Remove a person recorded by mistake (items stay) (admin)

#### Todos (待办)

The owner's todo list, kept on the hub's 待办 page; the same record as the public API's /todos. Each todo names who added it (owner or the key). Nothing deletes one.

- GET https://api.hub.jiajun.fyi/api/todos: Todos: open first by priority and due date (?status=&priority=&tag=&q=&cursor=&limit=) (todos:read)
- POST https://api.hub.jiajun.fyi/api/todos: Add ({title, note?, priority?, dueDate?, tags?}) (todos:write)
- PATCH https://api.hub.jiajun.fyi/api/todos/{id}: Change any field, or status (todos:write)
- POST https://api.hub.jiajun.fyi/api/todos/{id}/complete: Mark done (also reopen, drop) (todos:write)
- POST https://api.hub.jiajun.fyi/api/todos/reorder: Hand order ({ids}, first to last) (todos:write)

#### Admin

Owner tools. A key needs admin; backups take the internal token only.

- GET https://api.hub.jiajun.fyi/api/api-keys: List API keys (admin)
- POST https://api.hub.jiajun.fyi/api/api-keys: Create an API key (shown once) (admin)
- POST https://api.hub.jiajun.fyi/api/api-keys/{id}/revoke: Revoke a key (admin)
- GET https://api.hub.jiajun.fyi/api/api-keys/{id}/calls: A key's recent calls (admin)
- GET https://api.hub.jiajun.fyi/api/agents: The owner's agents (jiajun.fyi/agent) with their key state (agents:manage)
- POST https://api.hub.jiajun.fyi/api/agents: Create an agent and its pih_ key (shown once; never admin, always expires) (agents:manage)
- PATCH https://api.hub.jiajun.fyi/api/agents/{id}: Change an agent's permissions and its key's scopes in place (agents:manage)
- POST https://api.hub.jiajun.fyi/api/agents/{id}/{action}: rotate (new key, same scopes, old revoked) or revoke (agents:manage)
- GET https://api.hub.jiajun.fyi/api/webhooks: Callback webhook endpoints (?keyId=) (admin)
- POST https://api.hub.jiajun.fyi/api/webhooks: Register an endpoint for a key (signing secret shown once) (admin)
- POST https://api.hub.jiajun.fyi/api/webhooks/{id}/{action}: test, disable, enable, rotate-secret, move (to a new key) (admin)
- GET https://api.hub.jiajun.fyi/api/webhooks/{id}/events: Recent events with every delivery attempt (admin)
- POST https://api.hub.jiajun.fyi/api/webhooks/events/{id}/redeliver: Send an event again (admin)
- GET https://api.hub.jiajun.fyi/api/settings/collect-webhook: Read, rotate (POST) or disable (DELETE) the collect webhook (admin)
- GET https://api.hub.jiajun.fyi/api/settings/flomo: Flomo settings (PUT, DELETE) (admin)
- GET https://api.hub.jiajun.fyi/api/model-runs/summary: Model cost summary (admin)
- GET https://api.hub.jiajun.fyi/api/tikhub/budget: TikHub budget (PUT to change) (admin)
- GET https://api.hub.jiajun.fyi/api/notifications/channels: Notification channels (admin)
- POST https://api.hub.jiajun.fyi/api/notifications/send: Send a notification (admin)
- GET https://api.hub.jiajun.fyi/api/notifications/log: Delivery log (admin)
- GET https://api.hub.jiajun.fyi/api/system/capabilities: System status (admin)
- POST https://api.hub.jiajun.fyi/api/payloads: Keep a raw payload (admin)
- GET https://api.hub.jiajun.fyi/api/backup/rows: Table rows for the nightly backup (internal token only)

#### No credential

These carry their own proof: a secret in the path, a signature, or a public item.

- GET https://api.hub.jiajun.fyi/health: Health check (none)
- POST https://api.hub.jiajun.fyi/api/webhook/collect/{secret}: iOS share-sheet collect (GET with ?url= also works) (secret in the URL)
- POST https://api.hub.jiajun.fyi/api/webhook/things/{secret}: 记到想买 from a Shortcut or any tool: {text} / {url} / an image (GET with ?text= or ?url= also works) (secret in the URL)
- GET https://api.hub.jiajun.fyi/api/public/media/{id}: Signed media link (signature)
- GET https://api.hub.jiajun.fyi/api/public/items/{id}: Public fields of an item marked public (none)

### English Practice (english.jiajun.fyi)

Practice records, the Eudic word book, pronunciation scoring, and words in watched videos. Login only; agents read practice data through the public API's /english/*.

- Access: Login only: agents cannot call it
- Auth: Cloudflare Access (owner login)

#### Practice

- GET https://english.jiajun.fyi/api/english-practice: Practice records (POST adds one) (login)
- PATCH https://english.jiajun.fyi/api/english-practice/{id}: Update a record (mastery) (login)
- GET https://english.jiajun.fyi/api/english-practice/sync-state: Cursor for the practice sync (PUT moves it) (login)
- GET https://english.jiajun.fyi/api/english-practice/sources: Source prompts (POST adds) (login)
- GET https://english.jiajun.fyi/api/english-practice/known-terms: Terms already mastered (login)

#### Words and pronunciation

- GET https://english.jiajun.fyi/api/eudic-words: Words in a Eudic book, with sync status (login)
- PUT https://english.jiajun.fyi/api/eudic-words/star: Set a word's mastery (login)
- GET https://english.jiajun.fyi/api/eudic-words/star-events: A word's mastery history (login)
- GET https://english.jiajun.fyi/api/pronunciation/tts: Reference audio for a text (login)
- GET https://english.jiajun.fyi/api/pronunciation/attempts: Scored attempts (POST scores a new one) (login)
- GET https://english.jiajun.fyi/api/pronunciation/recording: A recorded attempt (login)
- GET https://english.jiajun.fyi/api/word-clips: Moments in watched videos where a word is spoken (login)
- GET https://english.jiajun.fyi/api/word-clips/clip/{id}: A sentence clip (login)
- GET https://english.jiajun.fyi/api/word-clips/media/{id}: The full media file (login)

### Recipes (recipes.jiajun.fyi)

Recipes extracted from the library, the week's meal plan and the grocery list. Login only.

- Access: Login only: agents cannot call it
- Auth: Cloudflare Access (owner login)

- GET https://recipes.jiajun.fyi/api/recipes: All recipes (login)
- GET https://recipes.jiajun.fyi/api/recipes/{n}: One recipe (login)
- PUT https://recipes.jiajun.fyi/api/recipes/{n}/want: Mark as want to cook (login)
- POST https://recipes.jiajun.fyi/api/recipes/{n}/cooked: Log that it was cooked (login)
- GET https://recipes.jiajun.fyi/api/items/{id}/recipes: Recipes cut from one library item (login)
- GET https://recipes.jiajun.fyi/api/plan: The week's meal plan (POST adds, DELETE /api/plan/{n} removes) (login)
- GET https://recipes.jiajun.fyi/api/grocery: The week's grocery list (POST adds, DELETE /api/grocery/{n} removes) (login)
- PUT https://recipes.jiajun.fyi/api/grocery/check: Tick grocery items (login)
- GET https://recipes.jiajun.fyi/api/media/{id}: A recipe's picture or video (login)

### Evals (evals.jiajun.fyi)

My own model and engine comparisons, and the test sets they reuse. Login only; bench scripts import with the jc-evals Access service token (docs/evaluations.md).

- Access: Login only: agents cannot call it
- Auth: Cloudflare Access (owner login, or the jc-evals service token for imports)

- GET https://evals.jiajun.fyi/api/evaluations: All evaluations (POST imports one, upsert by slug) (login)
- GET https://evals.jiajun.fyi/api/evaluations/{slug}: One evaluation with its samples and files (login)
- PUT https://evals.jiajun.fyi/api/evaluations/{slug}/files/{name}: Store a raw file in R2 (GET reads it back) (login)
- GET https://evals.jiajun.fyi/api/test-sets: Test sets (POST saves one) (login)
- GET https://evals.jiajun.fyi/api/test-sets/{slug}: One test set and the evaluations run on it (login)
- GET https://evals.jiajun.fyi/api/test-sets/candidates: Library items that could join a test set (login)

### Caltrain Commute (caltrain.jiajun.fyi)

Live Caltrain predictions and commute reminders. /status is public; the settings page needs a login.

- Access: Public
- Auth: None for /status; /settings behind Cloudflare Access; /api/action takes the hub's internal token

- GET https://caltrain.jiajun.fyi/status: Live train predictions (JSON); with ?from=&to= station ids, any station pair from the timetable (none)
- GET https://caltrain.jiajun.fyi/stations: Station ids and names, north to south (none)
- GET https://caltrain.jiajun.fyi/passings: When commute trains really left the two boarding platforms (last 30 days) (none)
- GET https://caltrain.jiajun.fyi/health: Health check (none)
- GET https://caltrain.jiajun.fyi/settings: Reminder settings (?format=json; POST saves) (login)
- POST https://caltrain.jiajun.fyi/api/action: Button actions from the Feishu bot (internal token)

### Share pages (share.jiajun.fyi)

Web pages for items marked public. HTML only, not a JSON API.

- Access: Public
- Auth: None

- GET https://share.jiajun.fyi/{id}: The public page of one item (none)

## Elsewhere on jiajun.fyi

- hub.jiajun.fyi: The library's web app (login). Its /api is the internal API above, proxied.
- api.jiajun.fyi: Media gateway to the home inference machines (transcription, chat, page fetch). Its own key; used by the library's jobs, not by agents.
- suanming.jiajun.fyi: Divination research desk: content library, crawl jobs, charts (login). Its /api serves only its own page; no API keys.
- jiajun.fyi: Directory of every service (login).
- admin.jiajun.fyi: The library's admin site (owner login only). Its /api is the internal API above, proxied.

## Onboarding prompt

Paste into a coding agent or chat assistant: https://dev.jiajun.fyi/agent.txt