Repos

API

Every endpoint under a novem repo: lifecycle, metadata, build config, git browsing, variables, sharing and threads.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

A repo is a git repository novem hosts and (for the job type) builds into a container image. It follows the same conventions as the rest of the novem API: the filesystem metaphor, the HTTP verbs, plain-text writes, and the r/w/d permission model. See the API overview for the general mechanics and the repo guide for the concepts. This page lists the endpoint tree.

Every path below also answers OPTIONS with the verbs valid for your token.

Addressing a repo

Path	Use
`/v1/code/repos/:repo`	Your own repos (shorthand for your username)
`/v1/users/:user/code/repos/:repo`	Any user's repos, yours or ones shared with you

Both serve the same tree. When you address another user's repo your access is decided by its shares: reads need a share granting r, writes w, deletes d. The examples below use the /code/repos form.

Note these are the management endpoints. The git data itself is pushed and pulled with ordinary git tooling against the clone url published at the repo's url path. See pushing code.

Lifecycle

Verb	Path	Description
`GET`	`/code/repos`	List your repos
`PUT`	`/code/repos/:repo`	Create a repo; comes up as the `job` type
`GET`	`/code/repos/:repo`	List the repo's files and folders
`PATCH`	`/code/repos/:repo`	Rename; body is the new id (`text/plain`)
`DELETE`	`/code/repos/:repo`	Delete the repo

Metadata

Verb	Path	Description
`POST` / `GET` / `DELETE`	`/code/repos/:repo/name`	Display name
`POST` / `GET` / `DELETE`	`/code/repos/:repo/summary`	One-line summary
`POST` / `GET` / `DELETE`	`/code/repos/:repo/description`	Longer description, rendered as markdown
`GET`	`/code/repos/:repo/shortname`	The repo's unique short id
`GET`	`/code/repos/:repo/url`	Git clone url
`GET`	`/code/repos/:repo/log`	Repository and build log: pushes, selected heuristic, progress, and per-ref failure details

DELETE on a metadata file truncates it (clears the content) rather than removing the path.

Configuration

Config keys are plain-text files supporting POST (write), GET (read) and DELETE (reset to default). GET on config and its sub-folders lists the keys.

Path	Default	Description
`config/type`	`job`	Build type: `job` builds a chain-runnable image on every push; `code` is plain git hosting with no build
`config/branch/default`	`main`	The branch `latest` tracks and novem checks out by default — the branch must already exist on the repo
`config/options/comments`	`true`	Set to `false` to block new comment threads on the repo
`config/build/cpu`	(host)	Whole CPU cores the image build is pinned to. Unset lets the builder use the host's cores
`config/build/mem`	`4g`	Memory for the image build. Takes a unit — `m` or `g`
`config/build/disk`	`4g`	Builder disk. Raise it when a large image fails while assembling its filesystem

config/build_disk is the older spelling of config/build/disk and still works; if both are set, config/build/disk wins.

What your plan allows

Build resources are capped per plan. A value above your ceiling is stored capped rather than refused, and the write records a message on the repo saying what it was reduced to.

Plan	`cpu`	`mem`	`disk`
Free	2	4g	4g
Basic	4	6g	8g
Premium	8	8g	20g
Enterprise	12	12g	20g

Image labels

Each push to a job repo publishes its image under a fixed set of labels. A job or chain picks one by writing it after the repo name, as in @alice/data_fetcher:prod. With no label it gets latest.

Label	Points at
`latest`	The tip of the default branch (`config/branch/default`)
`head`, `dev`, `test`	The same commit as `latest`
`tag:<name>`	The commit the git tag `<name>` points at, one label per tag
`tag`	The newest tag's commit, or the same commit as `latest` when the repo has no tags
`prod`	The same commit as `tag`
`commit:<sha>`	That commit, by its full 40-character sha, for each commit in the default branch's history and each tagged commit

The newest tag is decided by creation time: an annotated tag by the time it was tagged, a lightweight tag by its commit's date. So pushing a tag moves tag and prod to it, unless it is a lightweight tag on a commit older than the current newest tag.

A label is matched by its exact name, and nothing else is looked up:

Branches other than the default get no label. Pushing a branch called dev or prod changes nothing, because those labels follow the default branch and the newest tag.
A tag is tag:<name>, not the bare name. Pin release v1.0.0 with @alice/data_fetcher:tag:v1.0.0.
A name outside this set is refused. Writing it as a job's repo reference returns 404 with Reference "<name>" not found, and a chain step naming it fails the run with "No usable image".

Note: prod equals latest until the repo has its first tag, so a job pinned to :prod on an untagged repo runs whatever the default branch holds. Tag the commit you want in production to pin it.

GET /code/repos/:repo/refs lists latest, head, dev, test, prod and one entry per tag, each linking to its commit. Tag entries are named without the tag: prefix (v1.0.0). The tag and commit:<sha> labels are not listed, and branches are under /code/repos/:repo/branches.

Browsing git contents

novem exposes a read-only view of the pushed history. Everything under a commit is content-addressed and therefore immutable, and served with a long-lived cache. These endpoints are GET-only.

Path	Description
`/code/repos/:repo/branches`	Branches, each with its tip `commit_sha`
`/code/repos/:repo/refs`	The image's labels, each with the commit it points at
`/code/repos/:repo/commits`	Commit list — `sha`, `message`, `author`, `author_date`
`/code/repos/:repo/commits/:sha`	One commit — adds `tree_sha`, `parent_sha`, `committer` and dates
`/code/repos/:repo/commits/:sha/message`	That commit's message
`/code/repos/:repo/commits/:sha/files`	The tree at the repo root for that commit
`/code/repos/:repo/commits/:sha/*`	Browse any path within the commit — a directory lists its entries, a file returns the blob (JSON metadata, or the raw bytes)

Note: :sha is a full 40-character commit SHA. Paths are validated (no traversal, control characters or excessive depth), and a blob over the service limit returns 422 rather than streaming.

Variables

Repos support novem vars, live values you can reference from comments, descriptions and document content:

Verb	Path	Description
`GET`	`/code/repos/:repo/vars`	List the repo's vars
`PUT` / `GET` / `DELETE`	`/code/repos/:repo/vars/:var`	Create, inspect or remove a var
`POST` / `GET` / `DELETE`	`.../vars/:var/value`	The var's value
`POST` / `GET` / `DELETE`	`.../vars/:var/type`	`relative`, `number` (default), `date` or `text`
`POST` / `GET` / `DELETE`	`.../vars/:var/format`	Format string (no default)
`POST` / `GET` / `DELETE`	`.../vars/:var/threshold`	Threshold for `relative` vars (default `0`)
`POST` / `GET` / `DELETE`	`.../vars/:var/about`	Short description
`GET`	`.../vars/:var/out.txt`	The formatted value, plain text
`GET`	`.../vars/:var/out.ansi`	The formatted value, ansi

Verb	Path	Description
`GET`	`/code/repos/:repo/shared`	List who the repo is shared with
`PUT` / `DELETE`	`/code/repos/:repo/shared/:group`	Add or remove a share: `public`, `@user~group` or `+org~group`
`GET`	`/code/repos/:repo/tags`	List the repo's tags
`PUT` / `DELETE`	`/code/repos/:repo/tags/:tag`	Tag or untag the repo
`GET`	`/code/repos/:repo/threads`	List comment-thread topics
`GET` / `PUT` / `POST` / `DELETE`	`/code/repos/:repo/threads/*`	Read and write topics, comments and reactions

Note: creating, updating or deleting threads, comments and reactions requires a paid subscription (basic and up). Reading threads is available on all plans, and the owner can turn comments off entirely via config/options/comments.