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.
| 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.
| 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 |
| 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 | Build log; records which build heuristic ran |
DELETE on a metadata file truncates it (clears the content) rather than
removing the path.
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/comments | true | Set to false to block new comment threads on the repo |
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 | All refs (branches and tags) |
/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.
Repos support novem vars, live values you can reference from comments, mails, and docs:
| 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 (default), number, date or text |
POST / GET / DELETE | .../vars/:var/format | Format string |
POST / GET / DELETE | .../vars/:var/threshold | Threshold for relative vars |
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/comments.
- Repo guide — concepts, build types and pushing code.
- Repo quick start — create, push and build end to end.
- Jobs — run the image a
jobrepo builds. - API overview — verbs, permissions and sharing.