Artifact [42767db3d9]

Artifact 42767db3d9495a05e2ecaf0f1feb63f4950e6242856df4c400eb25110562170d:

• File docs/api.md — part of check-in [4a3165db34] at 2026-08-18 11:17:05 on branch trunk — repo.list: filter, sort and page the listing

  The front page rendered every repository unsorted and unbounded — the same shape that made the timeline unusable, and it is at 23 now. Adds a name filter, sort by name, recent activity or size, and a limit, with Total alongside Count so a page can say '5 of 23'.

  Sorting happens BEFORE the limit. The other order gives an arbitrary subset in the right sequence, which reads as correct and is not.

  Activity comes from the event table's index — one walk stopping at the first row — so the column that makes a forge listing worth reading costs nothing.

  Adds repo.get, so the settings page and the CLI stop scanning the whole listing to read one repository's settings. (user: dmestas, size: 18532) [annotate] [blame] [check-ins using]

# quarry API

Generated from the op registry by `quarry docs` — edit the ops, not this file; regenerate with `make docs`.
Every op also appears in the OpenAPI document (`quarry spec`). Query inputs ride the query string; the same names work as JSON.

## account.add

`POST /api/v1/accounts` — command, admin

Create a forge account. The password is hashed with argon2id and never stored or returned in plaintext.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `password` | string | `required,max=1024` |
| `admin` | boolean | — |

Output fields:

- `name` (string)
- `admin` (boolean)

## account.delete

`POST /api/v1/accounts/delete` — command, admin

Delete an account and all of its grants.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |

Output fields:

- `name` (string)

## account.grant

`POST /api/v1/accounts/grant` — command, admin

Grant an account read, write or admin on one repository.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `repo` | string | `required,max=64` |
| `role` | string | `required,oneof=read\|write\|admin` |

Output fields:

- `name` (string)
- `repo` (string)
- `role` (string)

## account.list

`GET /api/v1/accounts` — query, admin

List forge accounts and their per-repository grants.

Output fields:

- `accounts` (array of object {Account: object {name: string, admin: boolean, created: string}, grants: array of object {repo: string, role: string}})
- `count` (integer)

## account.passwd

`POST /api/v1/accounts/passwd` — command, admin

Set an account's password.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `password` | string | `required,max=1024` |

Output fields:

- `name` (string)

## account.revoke

`POST /api/v1/accounts/revoke` — command, admin

Remove an account's grant on one repository.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `repo` | string | `required,max=64` |

Output fields:

- `name` (string)
- `repo` (string)
- `role` (string)

## archive.get

`GET /api/v1/r/{repo}/archive/{version}` — query, anonymous

Download a check-in's files as a reproducible gzip tar archive.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `version` | string | `max=100` |

Output fields:

- `name` (string)
- `size` (integer)
- `content` (string)

## attachment.get

`GET /api/v1/r/{repo}/attachment/{hash}` — query, anonymous

Fetch one attachment's content by its content-artifact hash.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `hash` | string | `required,min=4,max=64` |

Output fields:

- `name` (string)
- `size` (integer)
- `content` (string)

## branch.list

`GET /api/v1/r/{repo}/branch` — query, anonymous

List branches with their tip check-in, most recently active first.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `branches` (array of object {name: string, tip: string, date: string})
- `count` (integer)

## checkin.diff

`GET /api/v1/r/{repo}/checkin/{hash}/diff` — query, anonymous

Diff one check-in against its primary parent.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `hash` | string | `required,min=4,max=64` |

Output fields:

- `from` (string)
- `to` (string)
- `files` (array of object {status: string, name: string})
- `unified` (string)
- `note` (string)

## checkin.get

`GET /api/v1/r/{repo}/checkin/{hash}` — query, anonymous

Describe one check-in: metadata, parents, and its file set.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `hash` | string | `required,min=4,max=64` |

Output fields:

- `hash` (string)
- `ci` (string)
- `branch` (string)
- `date` (string)
- `user` (string)
- `comment` (string)
- `parents` (array of string)
- `files` (array of object {blob: string, name: string, size: integer, perm: string, binary: boolean})

## ci.list

`GET /api/v1/r/{repo}/ci` — query, anonymous

List a repository's CI runs, newest first.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `limit` | integer | `min=0,max=200,default=50` |

Output fields:

- `runs` (array of object {runId: string, checkin: string, workflow: string, pipeline: string, status: string, started: string})
- `count` (integer)

## file.get

`GET /api/v1/r/{repo}/file/{hash}/{path...}` — query, anonymous

Fetch one file's content at a check-in.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `hash` | string | `required,min=4,max=64` |
| `path` | string | `required,max=512` |

Output fields:

- `hash` (string)
- `path` (string)
- `size` (integer)
- `binary` (boolean)
- `content` (string)
- `html` (string)

## file.history

`GET /api/v1/r/{repo}/history/{version}/{path...}` — query, anonymous

List the check-ins that changed one file, newest first.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `version` | string | `max=100` |
| `path` | string | `required,max=1024` |
| `limit` | integer | `min=0,max=200,default=50` |

Output fields:

- `path` (string)
- `version` (string)
- `changes` (array of object {hash: string, date: string, user: string, comment: string})
- `count` (integer)

## fleet.status

`GET /api/v1/fleet` — query, admin

Report every served store's ingest health.

Output fields:

- `repos` (array of object {name: string, code: string, checkins: integer, indexing: boolean, health: object {lastOk: string, roundSeconds: number, lastCount: integer, total: integer, fallbacks: integer, lastErr: string, lastErrAt: string, failures: integer}})
- `count` (integer)
- `unhealthy` (integer)

## fleet.sync

`POST /api/v1/fleet/sync` — command, admin

Run an ingest round now — one store, or every store when `repo` is empty.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `max=64` |

Output fields:

- `results` (array of object {repo: string, artifacts: integer, err: string})
- `failed` (integer)

## forum.get

`GET /api/v1/r/{repo}/forum/{root}` — query, anonymous

Fetch one forum thread: every post, rendered, in reading order.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `root` | string | `required,min=4,max=64` |

Output fields:

- `root` (string)
- `title` (string)
- `posts` (array of object {hash: string, parent: string, date: string, user: string, html: string})

## forum.list

`GET /api/v1/r/{repo}/forum` — query, anonymous

List a repository's forum threads, most-recently-active first.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `threads` (array of object {root: string, title: string, posts: integer, updated: string, user: string})
- `count` (integer)

## forum.post

`POST /api/v1/r/{repo}/forum` — command, token

Open a new forum thread.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `title` | string | `required,max=200` |
| `body` | string | `required,max=1048576` |
| `mimetype` | string | `max=64` |

Output fields:

- `hash` (string)

## forum.reply

`POST /api/v1/r/{repo}/forum/{root}` — command, token

Reply to a forum post within its thread.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `root` | string | `required,min=4,max=64` |
| `body` | string | `required,max=1048576` |
| `mimetype` | string | `max=64` |

Output fields:

- `hash` (string)

## meta.docs

`GET /api/v1/docs` — query, anonymous

The API reference, generated from this registry and rendered.

Output fields:

- `markdown` (string)
- `html` (string)

## meta.version

`GET /api/v1/version` — query, anonymous

Report the quarry build version.

Output fields:

- `version` (string)

## mirror.delete

`POST /api/v1/mirrors/delete` — command, admin

Stop mirroring a store and forget its upstream.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `repo` (string)

## mirror.list

`GET /api/v1/mirrors` — query, admin

List configured upstream mirrors and their recent history.

Output fields:

- `mirrors` (array of object {repo: string, url: string, every: integer, enabled: boolean, lastAt: string, lastOk: string, lastErr: string, failures: integer})
- `count` (integer)

## mirror.run

`POST /api/v1/mirrors/run` — command, admin

Pull from upstream now — one store, or every configured mirror when `repo` is empty.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `max=64` |

Output fields:

- `results` (array of object {repo: string, changed: boolean, err: string})
- `failed` (integer)
- `changed` (integer)

## mirror.set

`POST /api/v1/mirrors` — command, admin

Configure a store's upstream and pull interval.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `url` | string | `required,max=2048` |
| `every` | integer | `min=0,max=604800,default=3600` |

Output fields:

- `mirror` (object {repo: string, url: string, every: integer, enabled: boolean, lastAt: string, lastOk: string, lastErr: string, failures: integer})

## repo.add

`POST /api/v1/repos` — command, admin

Serve a repository: an existing store at `path`, a new empty one (`create`), or a clone of `clone`. Cloning also records a mirror unless `noMirror`.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `path` | string | `max=4096` |
| `description` | string | `max=300` |
| `private` | boolean | — |
| `create` | boolean | — |
| `clone` | string | `max=2048` |
| `noMirror` | boolean | — |
| `mirrorEvery` | integer | `min=0,max=604800` |

Output fields:

- `name` (string)
- `path` (string)
- `mirrored` (boolean)

## repo.counts

`GET /api/v1/r/{repo}/counts` — query, anonymous

Count a repository's content by section — what the navigation shows.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `checkins` (integer)
- `wikiPages` (integer)
- `tickets` (integer)
- `forumThreads` (integer)
- `technotes` (integer)

## repo.get

`GET /api/v1/r/{repo}/info` — query, anonymous

Describe one repository: its settings and headline counts.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `name` (string)
- `lastActive` (string)
- `description` (string)
- `private` (boolean)
- `checkins` (integer)
- `tipDate` (string)
- `tipComment` (string)
- `indexing` (boolean)

## repo.list

`GET /api/v1/repos` — query, anonymous

List the served repositories with their tip check-in.

Input:

| field | type | rules |
|---|---|---|
| `q` | string | `max=64` |
| `sort` | string | `oneof=active\|name\|size` |
| `limit` | integer | `min=0,max=500` |

Output fields:

- `repos` (array of object {name: string, lastActive: string, description: string, private: boolean, checkins: integer, tipDate: string, tipComment: string, indexing: boolean})
- `count` (integer)
- `total` (integer)

## repo.remove

`POST /api/v1/repos/remove` — command, admin

Stop serving a repository. The store on disk is left untouched.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |

Output fields:

- `name` (string)

## repo.update

`POST /api/v1/repos/update` — command, admin

Set a repository's settings: description and visibility. Fields are applied whole.

Input:

| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `description` | string | `max=300` |
| `private` | boolean | — |

Output fields:

- `name` (string)
- `description` (string)
- `private` (boolean)

## search.query

`GET /api/v1/r/{repo}/search` — query, anonymous

Full-text search over a repository's check-ins, wiki, and tickets.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `q` | string | `required,max=200` |
| `limit` | integer | `min=0,max=200,default=50` |

Output fields:

- `results` (array of object {kind: string, ref: string, label: string, snippet: string})
- `count` (integer)

## technote.add

`POST /api/v1/r/{repo}/technote` — command, token

Record a technote; passing an existing event id records an edit.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `body` | string | `required,max=1048576` |
| `mimetype` | string | `max=64` |
| `comment` | string | `max=200` |
| `event` | string | `max=64` |

Output fields:

- `event` (string)
- `hash` (string)

## technote.get

`GET /api/v1/r/{repo}/technote/{event}` — query, anonymous

Fetch one technote, rendered, by event-id prefix.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `event` | string | `required,max=64` |

Output fields:

- `event` (string)
- `date` (string)
- `user` (string)
- `comment` (string)
- `body` (string)
- `html` (string)

## technote.list

`GET /api/v1/r/{repo}/technote` — query, anonymous

List a repository's technotes at their latest edit, newest first.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `notes` (array of object {hash: string, event: string, date: string, user: string, mimetype: string, comment: string, body: string})
- `count` (integer)

## ticket.get

`GET /api/v1/r/{repo}/ticket/{id}` — query, anonymous

Fetch one ticket: folded state plus change history.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `id` | string | `required,min=4,max=40` |

Output fields:

- `ticket` (object {id: string, created: string, updated: string, fields: array of object {name: string, value: string}, description: string, descriptionMimetype: string, comments: array of object {hash: string, date: string, login: string, username: string, mimetype: string, body: string}, changes: array of object {hash: string, date: string, user: string, fields: array of object {name: string, value: string}}})
- `descriptionHtml` (string)
- `comments` (array of object {date: string, login: string, username: string, html: string})
- `attachments` (array of object {hash: string, name: string, src: string, date: string, user: string})

## ticket.list

`GET /api/v1/r/{repo}/ticket` — query, anonymous

List a repository's tickets with their folded current state.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `limit` | integer | `min=0,max=200,default=50` |
| `before` | string | `max=96` |

Output fields:

- `tickets` (array of object {id: string, title: string, status: string, updated: string})
- `count` (integer)
- `next` (string)

## ticket.new

`POST /api/v1/r/{repo}/ticket` — command, token

Open a new ticket.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `title` | string | `required,max=200` |
| `status` | string | `max=40` |
| `comment` | string | `max=65536` |

Output fields:

- `id` (string)
- `hash` (string)

## ticket.set

`POST /api/v1/r/{repo}/ticket/{id}` — command, token

Record a ticket change; empty fields are left untouched.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `id` | string | `required,min=4,max=40` |
| `title` | string | `max=200` |
| `status` | string | `max=40` |
| `resolution` | string | `max=40` |
| `comment` | string | `max=65536` |

Output fields:

- `hash` (string)

## timeline.list

`GET /api/v1/r/{repo}/timeline` — query, anonymous

List a repository's events — check-ins, wiki edits, ticket changes — newest first, paged by `before`.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `limit` | integer | `min=0,max=200,default=50` |
| `before` | string | `max=96` |
| `branch` | string | `max=64` |
| `y` | string | `oneof=all\|ci\|w\|t\|e\|f` |

Output fields:

- `entries` (array of object {kind: string, hash: string, ref: string, date: string, user: string, comment: string, branch: string, isLeaf: boolean, isMerge: boolean, parents: array of string, ci: string})
- `count` (integer)
- `next` (string)

## tree.list

`GET /api/v1/r/{repo}/tree/{version}/{path...}` — query, anonymous

List one directory of a check-in, with the directory's README rendered.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `version` | string | `max=100` |
| `path` | string | `max=1024` |

Output fields:

- `version` (string)
- `path` (string)
- `entries` (array of object {name: string, path: string, dir: boolean, blob: string, files: integer, size: integer, exec: boolean, link: boolean, binary: boolean})
- `readme` (string)
- `readmeIn` (string)

## wiki.get

`GET /api/v1/r/{repo}/wiki/{name}` — query, anonymous

Fetch one wiki page, rendered — latest, or the revision named by rev.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `name` | string | `required,max=100` |
| `rev` | string | `max=64` |

Output fields:

- `hash` (string)
- `title` (string)
- `date` (string)
- `user` (string)
- `mimetype` (string)
- `source` (string)
- `html` (string)

## wiki.history

`GET /api/v1/r/{repo}/wiki/{name}/history` — query, anonymous

List every recorded edit of one wiki page, newest first.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `name` | string | `required,max=100` |

Output fields:

- `title` (string)
- `edits` (array of object {hash: string, date: string, user: string})
- `count` (integer)

## wiki.list

`GET /api/v1/r/{repo}/wiki` — query, anonymous

List a repository's wiki pages with their latest edit.

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |

Output fields:

- `pages` (array of object {title: string, date: string, user: string})
- `count` (integer)

## wiki.save

`POST /api/v1/r/{repo}/wiki/{name}` — command, token

Record a wiki page edit (creates the page on first save).

Input:

| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `name` | string | `required,max=100` |
| `body` | string | `required,max=1048576` |
| `mimetype` | string | `max=64` |

Output fields:

- `hash` (string)