# 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 archive (tar.gz or zip).
Input:
| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `version` | string | `max=100` |
| `format` | string | `oneof=tar\|zip` |
Output fields:
- `name` (string)
- `size` (integer)
- `version` (string)
- `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})
## people.list
`GET /api/v1/people` — query, anonymous
List contributors across every repository the caller may read.
Input:
| field | type | rules |
|---|---|---|
| `repo` | string | `max=64` |
| `q` | string | `max=100` |
| `offset` | integer | `min=0,max=1000000` |
| `limit` | integer | `min=0,max=500,default=100` |
Output fields:
- `people` (array of object {user: string, events: integer, first: string, last: string, repos: array of string})
- `count` (integer)
- `total` (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` |
| `readme` | boolean | — |
| `license` | string | `max=16` |
| `ignore` | boolean | — |
| `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)
- `contributors` (integer)
- `tags` (integer)
## repo.delete
`POST /api/v1/repos/delete` — command, admin
Destroy a repository: its store, its index and everything keyed to it. `confirm` must equal `name`. Only repositories quarry created can be deleted.
Input:
| field | type | rules |
|---|---|---|
| `name` | string | `required,max=64` |
| `confirm` | string | `required,max=64` |
Output fields:
- `name` (string)
## 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)
- `contributors` (integer)
- `mirroredAt` (string)
- `deletable` (boolean)
- `fossilClone` (boolean)
- `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, contributors: integer, mirroredAt: string, deletable: boolean, fossilClone: boolean, 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.all
`GET /api/v1/search` — query, anonymous
Full-text search across every repository the caller may read.
Input:
| field | type | rules |
|---|---|---|
| `q` | string | `required,max=200` |
| `kind` | string | `oneof=checkin\|wiki\|ticket\|forum\|technote` |
| `repo` | string | `max=64` |
| `limit` | integer | `min=0,max=200,default=50` |
Output fields:
- `results` (array of object {repo: string, SearchResult: object {kind: string, ref: string, label: string, snippet: string}})
- `count` (integer)
- `searched` (integer)
- `by_repo` (array of object {repo: string, count: integer})
## 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` |
| `kind` | string | `oneof=checkin\|wiki\|ticket\|forum\|technote` |
| `limit` | integer | `min=0,max=200,default=50` |
Output fields:
- `results` (array of object {kind: string, ref: string, label: string, snippet: string})
- `count` (integer)
## tag.list
`GET /api/v1/r/{repo}/tag` — query, anonymous
List release tags — symbolic names that are not branches.
Input:
| field | type | rules |
|---|---|---|
| `repo` | string | `required,max=64` |
| `limit` | integer | `min=0,max=500,default=100` |
Output fields:
- `tags` (array of object {name: string, tip: string, date: 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` |
| `closed` | boolean | — |
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)