Config

Like every novem resource, a job is a folder of small files: each setting is read with GET, set with POST (plain text body), and cleared with DELETE. The job itself is created with PUT, renamed with PATCH and removed with DELETE on its base path, /v1/code/jobs/<job>. GET /v1/code/jobs lists your jobs; GET .../jobs/<job> lists a single job's entries.

Config keys

Everything under config/ controls how and when the job runs:

Example: pause a job without touching its schedule:

false

Legacy runtime keys

The route tree also carries config/extract, config/render, config/filter and config/group, which belong to the older single-image data / pdf runtimes. Writing those types to config/type (and configuring extract / render) requires the f_jobs feature flag and is not generally available. Stick with the default chains runtime.

Declaring invocation inputs

The six config/options leaves declare how a caller should invoke the job. Each of stdin, argv and input accepts one of three modes:

• no (the default) removes that input from the declared contract.
• optional advertises the input without requiring it.
• yes marks the input as required.

The adjacent <input>_description leaf explains what to provide. The job page uses the input declaration to hide file upload controls, offer optional uploads or require at least one file. The normalized contract is also exposed as JSON Schema in config.json_schema from GET /v1/i/<shortname>.

These settings describe the interface; they do not change scheduled execution or validate direct requests to the run API. In particular, stdin and argv are reserved for callers that understand the schema, while the current chains runtime continues to receive inputs through /input and starts the image with its own ENTRYPOINT/CMD.

What a run sees

Alongside your own config/env, every step of a run is told which job it is running as and which run it belongs to:

Together they name the run in progress, so a step carrying a novem token can address itself — read back its own runs/<run>/log, or publish the run's description — instead of guessing which job it was launched as.

A chain that references another job splices that job's steps in place; those steps report the job they came from and its own run, not the calling job's. If you set a config/env variable of the same name, yours wins.

Run credentials

A job is tokenless by default. Set config/access to a durable claim such as global, repo_ro or repo_rw when its code must call the novem API:

curl -X POST -H "Authorization: Bearer $NOVEM_TOKEN" \
  -H "Content-Type: text/plain" \
  --data 'repo_ro' \
  https://api.novem.io/v1/code/jobs/daily_report/config/access

Each run then receives its own short-lived credential in NOVEM_TOKEN, scoped to that claim. Novem revokes it when the run ends; its expiry bounds it if teardown cannot. Only steps belonging to the top-level job receive the token. A job spliced into a chain does not contribute its own credential.

If the job already stores a hand-pasted NOVEM_TOKEN under config/env, that legacy value wins over the generated credential. Delete the environment entry before adopting config/access; do not keep long-lived bearer tokens in job configuration.

Only the job owner can set or clear config/access. A credentialed job cannot also have a non-owner write share: anyone who can rewrite its chain or environment would otherwise choose the code that runs with the owner's credential. Clear the write share first, or share the job read-only (r or rx). Conversely, clear config/access before granting someone write access.

GET config/access shows the selected claim and its actions/access; DELETE clears it. An unset job continues to run normally but receives no NOVEM_TOKEN.

Build provenance

Every step is also told which revision of your code its image was built from:

These answer a different question than NOVEM_JOB does. The run identity says which job is running; the provenance says which code is running, which is what an audit trail or a sign-off needs after the fact.

The commit is read from the same record that decides which image gets pulled, so what a step reports and what it is actually running cannot disagree. Note that this is the commit the image was built from, not wherever the ref points now: push to latest and the ref advances immediately, while its image only changes when the build finishes. A run started in that window pulls the older image, and reports the older commit along with it.

Your repo needs no ARG, LABEL or --build-arg of its own; the answer is looked up per run rather than baked in at build time, so images built before this existed report their commit too.

Values are per step, from that step's own repo and ref. A chain that references another job splices in steps built from a different repo at a different commit, and each reports its own. As with the run identity, a config/env variable of the same name wins.

The same commit is written to the run's log beside each step's ref, so a finished run stays traceable once its containers are gone.

Metadata and related endpoints

Alongside config/ and runs, each job carries:

Next steps

• Chains — the pipeline grammar.
• Schedule — cron syntax and timezones.
• Runs — triggering, logs, output and retention.