The JSON API

All endpoints are under /api/v1. GET /api/v1 lists them. Each endpoint only reads, except POST /api/v1/reports. No endpoint writes to GitHub.

The API has no compatibility layer. The project changes, and old paths are removed, not redirected.

Endpoints

Paging

A list answer has these fields:

• items: at most limit rows. The default is 50, and the maximum is 200.
• total: the number of rows in the full list.
• next_cursor: the value to send as cursor for the next page, or null on the last page.

The cursor is opaque. A list can change between two requests, so a row can show twice or not at all.

GET /api/v1/prs

The queues:

• foryou: pull requests that need review and touch what login maintains, owns in ci/OWNERS or changed this year. It needs login or a session.
• unowned: pull requests that need review, with no maintainer.
• bumps: all open version bumps, the oldest first. With login, only what that login maintains.
• all: every pull request that needs review, the oldest first.
• ready: pull requests ready to merge. The other sections are the lists of the committer view.

Your subscriptions and tags are private. They count only when login is your own session. Then the answer has Cache-Control: private, no-store.

curl 'https://<host>/api/v1/prs?queue=unowned&limit=10'

GET /api/v1/people/<login>

It gives the public data of one login. It is the data of the profile page /u/<login>:

• facts: committer (true or false), packages and modules (the number it maintains), teams (the lib.teams teams that name it) and first_pr_at (the first pull request in the data, or null);
• open_prs: its open pull requests. The ones with no review for 7 days or more come first, the longest wait first. The others follow, the newest first;
• recent_prs: its pull requests merged or closed in the last 60 days, at most 20, the newest first;
• areas: the directories its pull requests of the last year change most, with the number of pull requests for each;
• person: whether its pull requests are in the queues;
• dossier and credits: its review record;
• area: what it maintains, owns and changed;
• maintains: its packages and NixOS modules, with their flags.

Each pull request in open_prs and recent_prs has these fields:

{
  "number": 123456,
  "title": "hello: 2.12.1 -> 2.12.2",
  "url": "https://github.com/NixOS/nixpkgs/pull/123456",
  "state": "OPEN",
  "base": "master",
  "created_at": "2026-10-01T12:00:00Z",
  "merged_at": null,
  "closed_at": null,
  "review": "no_review",
  "checks": "pass",
  "waiting_for_first_review": true
}

• review: draft, no_review, changes_requested, approved or reviewed. The last approval or change request of each reviewer counts.
• checks: pass, fail, pending, or null when it is not known.

It never ranks people. Private data, like subscriptions and tags, is never in it.

GET /api/v1/needs

It gives the items of Needs you: what waits for you, the most urgent first. It reads your session cookie only. Without a session, the answer is 401. The answer always has Cache-Control: private, no-store. Snoozed items are not in it.

mood keeps the items of one mood: all (the default), mine, machines, review or maintain. counts always gives the count of each mood.

{
  "login": "alice",
  "mood": "all",
  "counts": { "all": 2, "mine": 1, "machines": 1, "review": 0, "maintain": 0 },
  "items": [
    {
      "key": "adv:curl",
      "cause": "advisory",
      "title": "curl: NIXPKGS-2026-1",
      "detail": "On your machines. Upstream has 8.10.0.",
      "href": "/p/curl",
      "action": "Open the package",
      "fingerprint": "3f2a9c0d1b7e4a55",
      "moods": ["machines"],
      "labels": ["critical 9.8"],
      "at": null,
      "link": "https://tracker.security.nixos.org/issue/NIXPKGS-2026-1"
    }
  ]
}

• cause: advisory, reviewed, blocked, waiting, review or package. This is also the order of urgency.
• href: the page of the primary action, on this site.
• fingerprint: it changes when the state behind the item changes.
• at: the time of the event behind the item, or null.
• link: a second link, such as the advisory, or null.

GET /api/v1/packages/index

It gives the public package list of the current nixpkgs index. The client filters a closure with it before an upload (see personal.md). It is not paged.

{
  "rev": "<index revision>",
  "attrs": { "hello": ["hello", "2.12.1"] },
  "pnames": { "hello": ["hello"] }
}

• attrs: for each attribute, its pname and its version.
• pnames: for each pname, its attributes. The canonical one comes first.

The JSON is compact. Send Accept-Encoding: gzip to get it as gzip. The ETag is the index revision, and Cache-Control is public. Send the ETag back in If-None-Match to get a 304. Before the first index, the answer is 503.

The command line

The CLI reads the same API. --server sets the host, and --json prints the raw answer.

prs takes --section, --login, --limit and --cursor. It prints the next cursor on stderr.

The MCP server has the same data in its tools prs and person (see actions.md).