Feed API contract¶
All endpoints are served by gittok serve (default http://127.0.0.1:7313). Request and response bodies are JSON, except where a route says otherwise (/pair, /assets/*, /api/avatars/*, the web app). The routes are defined in src/gittok/api.py.
Routes¶
"Auth" is the same for every route unless the table says otherwise: see "Access rules".
| Method | Path | What it does |
|---|---|---|
| GET | /api/feed |
One page of the feed |
| GET | /api/cards/{id} |
One card |
| POST | /api/events |
Store a batch of reader events |
| POST | /api/answer |
Answer a quiz card |
| GET | /api/saved |
The saved cards |
| POST | /api/replies |
Reply to a comment |
| GET | /api/stories |
The stories row |
| POST | /api/stories/seen |
Mark story commits as seen |
| GET | /api/notifications |
The notifications |
| POST | /api/notifications/read |
Mark notifications as read |
| GET | /api/repos |
The configured repos |
| GET | /api/repos/{name} |
One repo's profile page |
| GET | /api/repos/{name}/map |
One repo's knowledge map |
| GET | /api/personas/{handle} |
One persona's page |
| GET | /api/files/{repo}/{path} |
One file's page |
| POST | /api/follows |
Follow or unfollow a path |
| GET | /api/prefs |
Reader preferences |
| GET | /api/avatars/{handle} |
A persona avatar image |
| GET | /assets/{folder}/{file} |
A card image or mascot image |
| POST | /pair/code |
Ask for a pairing code (no cookie needed; LAN serving only) |
| GET | /pair/wait |
Show the code with a Copy button, or set the pairing cookie once it is approved (no cookie needed) |
| GET | /pair.js |
The Copy button's script (no cookie needed) |
| GET | /healthz |
Liveness |
| GET | any other path | The web app (index.html for unknown paths) |
Access rules¶
The server checks each request in this order. The first check that fails answers the request.
- Host. The
Hostheader must be a known local name:127.0.0.1,localhost,[::1], one of this machine's LAN IPv4 addresses, its host name (also the short name and<short name>.local), or a name inserver.allowed_hosts(config/settings.yamlorlocal/settings.yaml). The port is ignored. Any other, missing or repeatedHostgets 421{"detail": "unknown Host", "code": "unknown_host"}. This applies to every path. - Origin. A request that is not
GET,HEADorOPTIONSand has anOriginheader whose host is not in the same list, or whose scheme or port differs from the request, gets 403{"detail": "cross-origin request", "code": "cross_origin"}. A request with noOriginpasses. - Pairing. When the server has a pairing token, a request that is not loopback needs the
cs_lancookie on every path except/pair/code,/pair/wait,/pair.js, and the app icons and manifest (/apple-touch-icon.png,/icon-192.png,/icon-512.png,/icon-maskable-512.png,/manifest.webmanifest). The server has a token whenever it binds a non-loopback address: withserver.lan: true(the default),--lan, or a non-loopback--host. It has none when LAN serving is off (server.lan: falseor--no-lan). Without the cookie,/api/*gets 401{"detail": "pair this device", "code": "unpaired"}and every other path gets a 401 HTML page. Loopback requests never need the cookie. The web app shows "This device is not paired" on a 401 from the feed. When the server has no pairing token, a request with a proxy header (see below) cannot pair, so it gets 403{"detail": "<text>", "code": "proxy_needs_pairing"}on every path. - Body size. A body over 1 MB gets 413
{"detail": "request body too large", "code": "body_too_large"}. AContent-Lengththat is not a number gets 400{"detail": "bad content-length", "code": "bad_content_length"}.
A request is "loopback" when the TCP peer has a loopback address and the request has none of the headers X-Forwarded-For, Forwarded, X-Forwarded-Host, X-Forwarded-Proto and X-Real-IP. A reverse proxy on the same machine connects from a loopback address and adds such a header, so its requests are not loopback: they need the pairing cookie when the server has a token, and they are refused when it has none. The server does not use the value of these headers. A proxy that sends none of them still counts as loopback: see docs/install.md, "HTTPS on a LAN".
Every response has Content-Security-Policy, X-Content-Type-Options: nosniff and Referrer-Policy: no-referrer (same-origin on the two pairing pages for a device that is not paired, so that their form posts its real Origin; see docs/social.md, "LAN access").
Errors¶
An error is an HTTP status plus a JSON body {"detail": "<text>", "code": "<code>"}. code is stable: a client can branch on it. detail is text for a person and can change.
| Status | code |
detail |
When |
|---|---|---|---|
| 400 | invalid_cursor |
invalid cursor |
GET /api/feed with a cursor the server cannot read |
| 400 | not_interactive |
card has no question to answer |
POST /api/answer for a card with no question |
| 400 | bad_choice |
text that names the bad choice | POST /api/answer with a choice the question does not have |
| 400 | bad_reply |
text that names the problem | POST /api/replies with an empty or too long text, or a bad comment_index |
| 400 | missing_ids |
send ids or all |
POST /api/notifications/read with neither ids nor all |
| 400 | bad_content_length |
bad content-length |
A Content-Length header that is not a number |
| 401 | unpaired |
pair this device |
/api/* from a device that is not paired |
| 403 | cross_origin |
cross-origin request |
A state-changing request with an Origin that is not a known local name |
| 403 | proxy_needs_pairing |
text that says to set server.lan: true |
A request with a proxy header when the server has no pairing token (LAN serving was turned off) |
| 404 | unknown_card |
unknown card <id> |
An unknown card id |
| 404 | unknown_repo |
unknown repo <name> |
An unknown repo name |
| 404 | unknown_persona |
unknown persona <handle> |
An unknown persona |
| 404 | unknown_asset |
unknown asset |
An unknown image under /assets/ |
| 413 | body_too_large |
request body too large |
A body over 1 MB |
| 421 | unknown_host |
unknown Host |
A Host header that is not a known local name |
Three errors do not have this shape:
- 422 (FastAPI validation):
{"detail": [{"type", "loc", "msg", "input", ...}]}. The body or a query parameter does not match the route's schema. Heredetailis a list, and there is nocode. - A 401 on a path outside
/api/is an HTML page, not JSON. - An error that the framework makes itself (404 for an unknown
/api/path, 405 for a wrong method) has onlydetail.
GET /api/feed¶
Query parameters: limit (1 to 50, default 20), cursor (the next_cursor of the page before), repo and dir (optional: only cards of that repo, or under that directory of it). A cursor that the server cannot read returns 400 invalid cursor.
A card once sent stays sent: a 👍 or 👎 does not reorder the cards the client already holds.
{
"cards": [Card, ...],
"next_cursor": "string or null",
"cursor": "string",
"resume_card_id": "string or null",
"generating": false
}
cursor names every card sent so far, also when the feed is exhausted (next_cursor is null then). Asked with it later, the feed returns only the cards made since. The web app does this at the end of the feed: every 10 s while generating is true, and when the app comes back on screen.
generating is true while a generation run is open (it started in the last agent.wake_cooldown_hours and has not finished). The end-of-feed card uses it to say that new cards are being made now. The client ignores it in an answer that comes from its offline cache.
resume_card_id is set only when there is no cursor. It is the card of the newest impression event, if that card still exists and is ready. The server puts that card first, so a reload opens on the card you saw last. The page still has limit cards. The card is also in the served list of next_cursor, so it is not repeated. With a cursor, or with no impressions, the value is null.
Card is the stored card spec (see schema/card.schema.json) plus server fields:
{
"id": "c_01H...",
"created_at": "2026-10-30T12:00:00Z",
"repo": "gittok",
"story_type": "hot_spot",
"format": "code_card",
"persona": "greybeard",
"tone": "dry-deadpan",
"hook": "This file has been edited 41 times in 90 days.",
"visual": { "kind": "code", "repo": "gittok", "path": "src/x.py", "commit": "<full sha>", "lines": [10, 24], "callouts": [{ "line": 12, "text": "..." }] },
"depth": [ { "kind": "explain", "text": "..." }, { "kind": "code", "repo": "...", "path": "...", "commit": "...", "lines": [1, 5] } ],
"comments": [ { "persona": "penny_learns", "text": "..." } ],
"sources": [ { "repo": "gittok", "commit": "<full sha>" } ],
"resolved": {
"visual": { "code": "line10\nline11\n...", "language": "python", "start_line": 10 },
"depth": [ null, { "code": "...", "language": "python", "start_line": 1 } ]
},
"links": {
"repo_url": "https://github.com/org/gittok",
"panels": [ null, "https://github.com/org/gittok/blob/<sha>/src/x.py#L1-L5" ],
"sources": [ { "label": "abc1234", "url": "https://github.com/org/gittok/commit/<sha>" } ]
}
}
links is null when the repo has no GitHub URL (see docs/formats.md).
resolved holds text the server read from git. The client renders code only from resolved, never from model output. For code_diff depth panels, resolved.depth[i] is { "diff": "<unified diff>" }. For text visuals, resolved.visual is null and the client uses visual.title, visual.body, visual.bullets.
GET /api/cards/{id}¶
One Card, with a replies list (the reader's replies on that card). 404 for an unknown id. The card is served in any status, also one that is not in the feed yet.
GET /api/repos¶
{ "repos": [ { "name": "...", "ref": "HEAD", "head_sha": "... or null", "group": null } ] }
One entry per configured repo. head_sha is the last analyzed commit, or null before the first analysis. An empty list means no repo is configured; the web app then shows how to add one in place of "You're all caught up".
GET /api/repos/{name}¶
{ "name": "storefront", "mascot": "otter or null", "mascot_image": "/assets/mascots/otter.png?v=<mtime> or null", "group": null,
"stats": { "commits_365": 120, "authors_365": 4, "last_commit_ts": 1730000000,
"top_files": [ { "path": "src/x.py", "commits": 41 } ], "top_dirs": [ { "path": "src", "commits": 90 } ] },
"verdicts": [ { "dir": "src", "counts": { "<verdict>": 3 } } ],
"cards": [Card, ...] }
cards holds the 20 newest ready cards of the repo. The numbers in stats are null (and the lists empty) before the first analysis or when the repo cannot be read. 404 for a repo that is not configured.
GET /api/repos/{name}/map¶
{ "name": "storefront",
"dirs": [ { "dir": "src", "cards_seen": 3, "cards_available": 9, "quiz_right": 1, "quiz_wrong": 0, "novelty": 0.7, "verdicts": { "<verdict>": 2 } } ],
"files": [ { "path": "src/x.py", "symbols_defined": 12, "symbols_seen": 4 } ] }
404 for a repo that is not configured.
GET /api/personas/{handle}¶
{ "handle", "name", "voice", "bio": "string or null", "posts": [Card, ...], "comments": [ { "card_id", "repo", "hook", "text" } ] }. 404 for an unknown persona.
GET /api/files/{repo}/{path}¶
path can hold slashes. Response: { "repo", "path", "history": { "commits": 41, "last_touched": "string or null", "authors": [ { "name", "commits" } ] } or null, "cards": [Card, ...], "followed": false }. cards are the cards that cite the path. 404 for a repo that is not configured; a path that is not in the repo still returns 200.
POST /api/follows¶
Body: { "repo": "storefront", "path": "src/billing", "on": true }. path is 1 to 400 characters; on defaults to true. Response: { "followed": true }. 404 for a repo that is not configured.
POST /api/events¶
{ "events": [ { "card_id": "c_...", "type": "impression", "ts": 1730000000000, "data": { "ms": 4200, "panel": 1 } } ] }
type is one of impression, dwell, skip, scroll_back, depth_open, lightbox_open, like, save, dislike, explain_more, answer, source_tap, beats_done, replay, beat_tap. knew_it and teach_more (retired buttons) are accepted and dropped, so an old queued batch does not fail; stored does not count them. ts is in milliseconds. card_id and data are optional. A batch holds at most 500 events, and each data is at most 4 KB as JSON.
Response: { "stored": 3 }. An unknown type, or a batch over a limit, is rejected whole with 422. The server writes the reason to <data_dir>/logs/rejected-events.log.
An event with a string data.event_id that the server stored before is ignored (the client retries a batch with the same ids); stored counts the new events only. A save event (data: {"on": bool}) also updates the saved_cards table in the same transaction. The newest event by ts wins. GET /api/saved reads that table, most recently saved first.
MCP get_packet(run_id, packet_id)¶
Not an HTTP route. A writer worker calls it for one work packet. Fields:
id,repo,repos,count,tier(lightorstandard: the worker model it needs),categories,story_types,formats,tones,personas,angles(one per card: the proposedwhat,how,why,whoorrisk).lead_refs: one object per lead, same order. Keys:story_type,repo,kind(commit,path, ornone),commit,path,lines([start, end]or null),text,id(the lead ledger row, or null for a lead computed on the fly).submit_cards(packet_id)usesidto mark the lead covered.packet_markdown: the packet, focus lines, and recent stories not to repeat.materials_markdown: evidence for the leads. A commit lead gets subject, author, date,--stat(15 files), and the diff of the most-changed file (80 lines). A path lead gets the blob sha, 60 numbered lines, top 3 blame authors, and first and last commit dates. At most 4 KB per lead (6 KB for an explaining story type) and 12 KB per packet, cut with[truncated]. Computed on each call, not stored.
The writing guidance comes from a second tool, get_guidance(run_id, packet_id): guidance_markdown, the card-writing rules and the section of each format the packet allows. When the packet has no meme menu, the meme list holds at most 12 templates, those that fit its story types first. Two calls, because one reply with both went over 50 KB, and Claude Code saves a reply that large to a file a writer cannot open. Each reply stays under mcp_server.MAX_REPLY_CHARS (40,000 characters).
finish_run returns seconds_per_card: run duration divided by accepted cards, rounded to 0.1 s (null when no card was accepted).
POST /api/answer¶
Body: { "card_id": "c_...", "choice": 0, "session": "..." }. Returns the reveal { "correct", "answer_index", "explanation" }. A card id that does not exist (for example, deleted by garbage collection) returns 404. A card with no question, or a bad choice, returns 400. The Quiz component shows "This card is gone." on 404 and does not retry.
GET /api/saved¶
{ "cards": [Card, ...] }, most recently saved first. Only ready cards of configured repos (the rule of the feed); GET /api/cards/{id} and POST /api/replies give 404 for any other card. Each card has a replies list.
POST /api/replies¶
Body: { "card_id": "c_...", "comment_index": 0, "text": "Why floats?" }. comment_index is the place of the comment in the card's comments. text is at most 280 characters and not empty.
Response: { "id": 4, "card_id": "c_...", "persona": "greybeard", "comment_index": 0, "text": "Why floats?", "created_at": "...", "answered_card_id": null }. 404 for an unknown card. 400 for an empty or too long text, or a comment_index that is out of range.
GET /api/stories¶
{ "stories": [ { "repo": "storefront", "mascot": "otter or null", "mascot_image": "string or null", "seen": false,
"digest": { "card_id": "c_...", "day": "2026-06-01", "hook": "...", "learn": "..." },
"commits": [ { "sha": "<full sha>", "short": "abc1234", "ts": 1730000000, "author": "Ann", "subject": "Fix it",
"files": 2, "seen": false, "card_id": "c_... or null", "url": "string or null" } ] } ] }
digest is absent or null when the repo has no digest card. url is the GitHub commit URL, only when no card covers the commit.
POST /api/stories/seen¶
Body: { "repo": "storefront", "shas": ["<7 to 40 hex characters>", ...] }, at most 100 shas. Response: { "recorded": 2 } (the number of shas that were new). 404 for a repo that is not configured. 422 for a bad sha.
GET /api/notifications¶
Query parameter: unread=1 returns only unread ones. Response:
{ "notifications": [ { "id": 7, "kind": "low_runway", "text": "...", "card_id": "c_... or null",
"created_at": "...", "read": false, "repo": "string or null" } ],
"unread": 3 }
Newest first. unread always counts every unread notification. repo is set only for hot_file notifications.
POST /api/notifications/read¶
Body: { "ids": [7, 8] } or { "all": true }. Response: { "unread": 1 }. A body with neither returns 400 send ids or all.
GET /api/prefs¶
{ "playback_speed": 1.0 }. The speed of beat cards; the set_playback_speed MCP tool changes it.
GET /api/avatars/{handle}¶
An image, not JSON: the persona's generated PNG when there is one, otherwise an SVG with initials. A leading @ in the handle is ignored. Any handle gets an image; there is no 404. Cache-Control: no-cache.
GET /assets/{folder}/{file}¶
A PNG from <data_dir>/assets. Two forms: /assets/<card id>/<number>.png (a card image; cached as immutable for a year) and /assets/mascots/<name>.png (cached for an hour). Any other name, or a missing file, returns 404 unknown asset. The URLs come from resolved.visual.images and mascot_image; clients do not build them.
GET /healthz¶
{ "ok": true }. A loopback request also gets "dir": the GitTok directory that this server belongs to. A session that finds the port in use reads it to tell the user which directory has the port. It follows the access rules like every other path.
MCP¶
The feed server has no MCP endpoint. The MCP server is a separate process (gittok mcp) that speaks stdio only. Its tools are not part of this contract, except the ones described below. SPEC.md, section 15, lists the tools.
The web app¶
Every other GET path serves the built web app; an unknown path serves index.html. Files under /_app/immutable/ are cached for a year, everything else is no-cache. A path that starts with api/ and matches no route returns 404. When the web app is not built, / returns a short HTML page that says how to build it.
MCP: feed_health and get_brief¶
feed_health() is a read-only MCP tool. gittok health prints the same JSON.
{ "backlog": 41, "by_repo": { "storefront": 30, "api-server": 11 }, "burn_per_day": 12.0, "runway_days": 3.4, "target_days": 3,
"want": 0, "pending_render": 2, "render_failed": 0,
"image_share": { "ready": 0.02, "shown_7d": 0.0 }, "db_mb": 3.1, "assets_mb": 0.6,
"gc": { "at": "2026-06-01T12:00:00Z", "counts": { "seen": 4, "liked": 0, "unseen": 1 } } }
backlog: ready cards that were never shown. Cards of a repo that is not configured do not count.by_repo: the backlog per configured repo.burn_per_day: distinct cards shown per day, mean of 7 days, never belowagent.min_burn_per_day.want: how many cards to make so the backlog lastsagent.target_runway_days. It is 0, or betweenagent.min_run_countandagent.max_count.gc: when the last real garbage collection pass ran and what it deleted, ornullbefore the first pass (see docs/learning.md).image_share: share of cards with a meme, illustration, comic, chart, or diagram visual.
get_brief(repo=None, count=None): without count, it makes want cards. When want is 0, it returns {"run_id": null, "nothing_to_do": true, "health": {...}}. It opens no run, analyzes no repo, and does not count toward per_day_runs. An explicit count always opens a run.
Once per UTC day, when runway_days < 1, the notify worker adds a low_runway notification (dedup_key low_runway:<date>).