tracker-api

name	tracker-api
description	Tracker's HTTP API — authenticate as a machine user, read tasks/meets/journals/today-board, ingest mail messages, write through the recording-mode gate via curl

Tracker API

Tracker exposes a single HTTP API at http://127.0.0.1:<port>/api/. Dev port is 3027. Request/response bodies are JSON. Use curl directly.

Tracker must be running locally (make start in tracker/) for any of this to work. Logs at tracker/logs/tracker.log.

The same /api/* endpoints the UI uses are also the machine-callable endpoints — what changes is who is calling and whether the recording-mode gate applies.

What tracker covers (scope)

Tracker is not only tasks. A single user's tracker holds tasks, meetings ("meets") and meeting series, recurring tasks, journals and journal entries, saved resources (links and videos), mottos, and "sources" — the user's YouTube channel subscriptions, podcast feeds, and Atom/RSS feeds plus their per-source settings. People / places / projects / goals are the categories that tie items together through relations.

So questions about the user's YouTube subscriptions, saved YouTube videos, podcasts, or RSS feeds are in scope and are answered from tracker — do not treat them as an external account you cannot reach. Subscriptions are under /api/sources/youtube/channels; saved videos/links are resources (/api/resources); podcast and feed sources under /api/sources/podcast and /api/sources/atom. For broad reads, prefer the specific resource endpoint (/api/tasks, /api/meets, /api/resources, /api/sources/...) over /api/today-board, which only covers today. When unsure of the exact path, consult /api/describe (below) — never refuse on the assumption that tracker does not track something.

Answering completely: act, filter, and size the read

• Act on reads. For a read-only question, fetch the data and answer — do not ask permission first ("shall I list them?"). Only ask back when the request is genuinely ambiguous.
• Find the filter before saying "no". List endpoints take query params (look them up in /api/describe): resources filter by domain/excluded-domains, tasks by scope/importance/urgency/category, meets by date/category. "My Google Docs" or "links from X" is a domain filter on /api/resources — a domain is not a category and not a missing feature.
• Put query params in the path, not a body. For GET reads, encode every query parameter directly in the path query string — GET /api/tasks?category=Acme&due-date=2026-06-22&limit=100. Parameters placed in a separate body/query/params field are dropped on a GET, so the filter and limit silently have no effect and you fall back to the default capped list (the machine-user list cap below). body is only for the JSON payload of POST/PUT writes.
• Lean rows by default — so enumerate and count freely. For machine-user (bot) callers, list reads on /api/tasks, /api/meets, /api/resources, /api/journals, /api/journal-entries, /api/recurring-tasks, /api/meeting-series return lean rows: description and tags are stripped, and the default cap is 100 (not 10). Lean rows are cheap, so for "all / how many / which" questions just filter and read the full set — listing titles and counting need no special care. Only for genuinely huge sets ("every task I have ever created") pass an explicit ?limit / paginate and state the scope you covered. Explicit counts ("top 5", "next 3") → pass that as ?limit.
• Ask for detail only when needed. To get the actual description / body text of list items, add ?detail=full (e.g. /api/tasks?category=Acme&detail=full) — use it when the user wants the contents, not for counting or listing titles. For one item's full detail, prefer GET /api/<type>/:id.
• Today and the next few days. /api/today-board is the bounded, full-detail view (never stripped). It is today-only by default; pass ?days=N to widen the meeting window to today..today+N for "the next few days" / the Today page. Reach for it on "what's on today / coming up" instead of scanning all tasks.
• Aggregate across types when the question spans them ("everything on Monday" = tasks and meets), and say which sources you checked. Never call a single filtered list "all" without confirming it covers the question.

Endpoint catalogue — ask the server

GET /api/describe returns a self-description of every public handler ({:name :ns :arglists :doc}); each :doc opens with VERB /api/path — ... and lists body fields, query params, views, sort modes, and notable error cases. That endpoint is the authoritative reference — this skill only covers how to use the API (auth, gating, identity, semantics, request patterns). It does not list endpoints, query params, or body fields. Always consult /api/describe for those — never guess from this document or from memory.

curl -sf http://127.0.0.1:3027/api/describe | jq '.[] | {ns, name}'

# Filter to one resource:
curl -sf http://127.0.0.1:3027/api/describe \
  | jq '.[] | select(.doc | startswith("POST /api/tasks"))'

If a user asks about a "view", "filter", "sort", or "tab" you don't recognise (e.g. "saved", "archived", "today"), look it up in /api/describe before answering — do not assume it doesn't exist.

Caller identity: regular users vs machine users

Tracker has two kinds of authenticated callers:

• Regular users — the human accounts that sign in to the web UI. Writes go through with no extra gating.
• Machine users — accounts created in admin → Users with the Machine user checkbox + a target user. They authenticate exactly like a regular user, but their JWT carries is-machine-user: true and a for-user-id claim. The server resolves all data access against for-user-id (so the machine acts on the bound user's tasks, meets, journals, mail, ...), and most write requests are gated by recording mode (see below). At most one machine user per regular user.

Read access for machine users is unrestricted.

Authentication

Dev mode (local)

Bound to 127.0.0.1. No credentials required. Pick the user with X-User-Id, or omit to target the first user.

curl -sf -H "X-User-Id: 3" http://127.0.0.1:3027/api/tasks?sort=today

In dev mode the recording-mode gate fires only when you send a real machine-user JWT. The X-User-Id path bypasses it.

Production mode

Every mutating /api/* request requires a Bearer JWT.

TOKEN=$(curl -sf -X POST http://tracker.example.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"my-machine","password":"s3cret"}' | jq -r .token)

curl -sf -H "Authorization: Bearer $TOKEN" \
  http://tracker.example.com/api/today-board

Admin: "username":"admin" + the server's ADMIN_PASSWORD.

The recording-mode gate

For machine-user callers, mutating requests (POST/PUT/DELETE) are intercepted before reaching the handler:

• The intent is logged to tracker/logs/tracker.log regardless of outcome.
• If recording mode is ON, the handler runs.
• If recording mode is OFF, the request returns {"dropped":true} (HTTP 200) and nothing hits the database.

Regular UI users are never gated.

Toggle from inside the UI with Alt+Shift+W (or POST /api/recording-mode/toggle). A red REC badge appears in the top bar. The toggle is human-only — agents must not flip it.

Gate exemptions

Some endpoints are exempt from the gate even for machine users — POST /api/messages (mail inbox ingestion) is the canonical example: mail is inbox-only noise until the human triages it in the UI, so the gate would only get in the way of automation. Check /api/describe for the authoritative exemption list per endpoint.

Common request patterns

Answering "what's on my today board?"

GET /api/today-board returns the aggregate {tasks, meets, journal-entries}. Tasks use the same :today filter as the UI's Today list (incomplete + due-date OR urgent/superurgent OR today=1 OR lined_up_for set OR active reminder). Meets are those with start_date = today and not archived. Journal entries are today's entries.

Adding mail to the inbox from a job

POST /api/messages bypasses the gate; requires has_mail on the (target) user.

Creating a task that should appear on Today

Two writes — create the task, then flip its today flag — and both hit the gate, so recording mode must be ON for a machine user to land them. Look up the exact endpoints + bodies in /api/describe.

Response-shape notes

A few shape details that aren't obvious from /api/describe docstrings:

• Task done and today are integers (0/1), not booleans.
• YouTube / Substack URLs posted to /api/resources auto-fetch their title server-side.