API

The HTTP API that the yard command talks to.

The yard command is a thin client for this API. Anything the command does, a script can do with curl.

Auth#

Every /api/v1/ call needs Authorization: Bearer <token>; a missing or bad token is a 401 unauthorized. On a host with no token, Yard makes the first one, admin, and writes it to tokens/admin.token. yard token new <name> makes another one. DELETE /api/v1/tokens/admin also removes that file, and no boot makes it again.

The hooks /hooks/origin and /hooks/github take no token. The GitHub hook verifies X-Hub-Signature-256 and answers 401 on a bad signature. The Origin hook has no signature to check. A push only asks for a check of the push apps on that repo, and an installation event makes Yard read the installations again. Yard then reads the tip from the forge and never trusts the event body. A body over 1 MiB is a 413.

curl -H "Authorization: Bearer $TOKEN" https://yard.example.com/api/v1/status

Errors#

An error is one JSON document:

{"error": {"code": "not_found", "message": "app heldso does not exist", "help": "Run yard app ls to see the apps on this host."}}

code and message are always present. code names the failure for a program. message is the short reason, and it names the bad value. help says what to do next, and it is optional.

Routes#

GET    /health                          200, empty
POST   /hooks/origin                    Origin events; 204, or 400/413 on a bad body
POST   /hooks/github                    GitHub events; 401 on a bad signature, 400/413 on a bad body, else 204
 
GET    /api/v1/status                   ?running=1                    → {host, rows}
GET    /api/v1/doctor                                                 → [{name, ok, detail, warn}]
GET    /api/v1/logs                     ?container&lines&since&until&after&hide&only&follow → text/plain, or JSON
GET    /api/v1/events                   ?app&container&source&event&lines&since&until&after&follow → JSON or NDJSON
POST   /api/v1/prune                    {days?: 7, dry?: false}       → {images, freed, days, dry, untagged, untagged_error}
 
GET    /api/v1/apps                                                   → [app]
POST   /api/v1/apps                     {name, repo | image | compose_url, ref?, runs?, trigger?} → {app}
GET    /api/v1/apps/{name}                                            → {app, image, sha, template_moved, env_file, dir, rows, hosts, deploy, log}
PATCH  /api/v1/apps/{name}              any of {repo, ref, runs, image, compose_url, trigger} → {app}
DELETE /api/v1/apps/{name}                                            → {name, hosts, caddy_error?}
POST   /api/v1/apps/{name}/deploy       {}                           → 202 {deploy}
GET    /api/v1/apps/{name}/deploy       ?follow=1 → {deploy} | x-ndjson
GET    /api/v1/apps/{name}/files/{which}  which: compose | containerfile → text/plain
 
GET    /api/v1/apps/{name}/env                                        → {KEY: VALUE}
PATCH  /api/v1/apps/{name}/env          {KEY: VALUE | null}           → {keys}
PUT    /api/v1/apps/{name}/env          {KEY: VALUE}                  → {keys}
 
GET    /api/v1/apps/{name}/caddy                                      → text/plain
PUT    /api/v1/apps/{name}/caddy        the site file as the body     → {hosts}
 
GET    /api/v1/forges                                                 → [forge]
POST   /api/v1/forges/{name}/installations                            → forge
PUT    /api/v1/forges/origin            {app_id}                      → {forge, app}
PUT    /api/v1/forges/github            {app_id, private_key, webhook_secret} → {forge, app}
 
POST   /api/v1/repos                    {name, owner?, forge?}        → {repo}
POST   /api/v1/repos/token              {repo}                        → {username, token, expires_at}
 
GET    /api/v1/tokens                                                 → [{name, created}]
POST   /api/v1/tokens                   {name}                        → {name, token}
DELETE /api/v1/tokens/{name}                                          → {name}

PATCH on the env sets each key and removes each key whose value is null. PUT replaces the whole file. A key with characters other than letters, digits, and _ is a 400 bad_key.

POST /api/v1/tokens takes a name with the app name rules, and yard-* is reserved: a 400 bad_name, or a 409 exists when the name is taken. DELETE of the token you use is a 403 forbidden, and an unknown token is a 404 not_found.

Apps#

An app is {name, repo, ref, runs, image, compose_url, trigger, created, deployed}. A name that exists is a 409 exists. trigger is push by default, or manual. deployed is {revision, runs, kind, reason, template, image} from the last ok deploy, or null.

An app has exactly one source:

  • repo — a full https://<host>/<owner>/<name> URL, and the host is github.com or origin.cursor.com. ref is a branch, main by default. runs says which file in the repo the app runs.

  • image — an image reference with a tag or a digest.

  • compose_url — an https:// URL of a compose file to fetch, 500 characters at most.

A POST with no name or no source is a 400 bad_json, and so is a PATCH that changes nothing. Two sources in one request are a 400 bad_source. A PATCH with a new source replaces the old one; a repo app that moves to an image or a compose URL drops its ref and runs. A move to another repo sets ref back to main and runs back to auto, unless the same request sets them. An empty source in a PATCH is a 400 bad_source. ref or runs on an app with no repo is a 400 bad_source.

runs is one of:

  • empty or auto — every deploy decides from the commit.

  • a path in the repo — a compose file or a Containerfile by content.

  • yard:<template> — one of the Containerfiles Yard writes: python-uv, python-pip, go, node-npm, http-nu.

A path is relative to the repo root: no leading /, no .., no :, no \, no spaces, and 200 characters at most. A runs with a : or an @ that is not a template is a 400 bad_runs whose help names --image. A PATCH with "runs": "" returns the app to auto.

Any field outside name, repo, ref, runs, image, compose_url, trigger is a 400 unknown_field whose help names the fields this Yard takes. The other errors are 400 bad_name (caddy and yard-* are reserved), bad_repo, bad_ref, bad_trigger, bad_runs, bad_image, bad_compose_url, and bad_path.

Every /api/v1/apps/{name} route answers a 404 not_found for an app that does not exist.

GET /api/v1/apps/{name} returns the full app page. app is the record as above, with deployed naming what the last ok deploy ran. image and sha are the running image and its revision: a commit for a repo app, the sha256: digest for an image app, and the sha256: of the file for a compose URL app. template_moved is true when the app runs a yard:<template> with another template stamp than this Yard has. dir is the app’s folder on the host. hosts lists the hosts of the site file. deploy is the last deploy record, or null (Deploys). The other keys are env_file, rows, and log.

GET /api/v1/apps/{name}/files/compose answers the compose files of the running deploy, as text/plain. One file is the text as it is; several files come each under a # <name> line. /files/containerfile answers the Containerfile that the running deploy built. An app that builds no image from a Containerfile, an app with no deploy yet, a file that is missing, or a repo file that points outside the clone is a 404 no_file whose message says why. Any which other than compose or containerfile is a 404 no_file too.

The env never appears in an app response. It has its own routes.

DELETE /api/v1/apps/{name} removes the app’s site file first, then its containers, clone, env file, and data. It does not ask: confirmation is the client’s job. hosts lists the hosts of the removed site. caddy_error is present only when Caddy did not load the config without the site. The yard app answers 400 forbidden.

GET /api/v1/doctor answers one row per check. ok is false for a failure. warn is true for a row that is ok but wants attention, such as an app with no healthcheck.

Status rows#

host is {cpus, mem, disk, cpu_used, mem_used, data_used, forges}; forges maps each forge to whether it is connected. A status row describes one container:

{app, container, service, state, running, health, restarts, exit_code,
 started, exited, id, oom, error, image, sha, tip, hosts, trigger, cpu, mem, data, deploy, template_moved}
  • id is the 12-character container id.

  • health is Podman’s healthcheck: healthy, unhealthy, or starting. It is failed for a container that is dead or exited with a code other than 0, down for an app with no container (its state is absent), and empty when the image has no healthcheck.

  • template_moved is true when the app runs a yard:<template> with another template stamp than this Yard has.

  • sha is the revision the container runs: a commit, or for an image or compose URL app the sha256: revision of its last ok deploy.

  • tip is the last revision that a check saw: the branch tip, the digest the tag points to, or the sha256: of the fetched file.

  • hosts lists the hosts of the app’s site file.

  • deploy is the last deploy record of the app, or null.

  • oom and error come from the inspect of a stopped container.

Deploys#

The deploy container deploy-<name> is the record of the last deploy. It stays after the deploy, so the record survives a Yard restart. A deploy record is:

{app, sha, image, status, cause, actor, previous, error, started, ended}

Yard reads status from the container: running while it runs, ok for exit code 0, reverted for exit code 3, and failed for any other code. The other values come from the container’s labels. Yard writes them all when it creates the container:

  • yard.revision, yard.image, yard.runs, yard.kind, yard.reason, and yard.template name the new plan.

  • The same keys under yard.before. name the plan before it.

  • yard.cause, yard.actor, and yard.error say why the deploy ran, who asked, and why it failed.

sha is the revision label, and previous is the before.image label. A deploy container with only the 0.12 labels sha and previous counts as no plan, so the next check deploys the app once. A deploy that fails before the apply, such as a git sync or a registry error, still leaves a failed container, and its log holds the deploy lines.

POST /api/v1/apps/{name}/deploy answers 202 with {deploy: {id, app, status, cause, actor, started, ended, image, error, previous}}. A second POST while it runs returns the same deploy. GET on the same route answers, in this order:

  1. The running deploy, with its lines.

  2. The record from the deploy container. An ok record also has port, the one TCP port the app container exposes, or 0.

  3. A deploy that did not run a container, such as skipped.

  4. A 404 when the app never deployed.

?follow=1 streams application/x-ndjson: one {"line": …} per buffered then live line, ending with {"deploy": {…}}. It ends at once when the deploy already ended. When Yard holds no deploy in memory, such as after a restart, ?follow=1 answers the plain record from the deploy container.

status is one of:

  • running — the deploy is in progress.

  • ok — the deploy finished. The new image is live.

  • failed — the deploy stopped; error says why, and the deploy log holds the lines. The previous version keeps running.

  • reverted — the new container never got healthy. The previous image runs.

  • skipped — YARD_SKIP_DEPLOY is set. Nothing ran.

The deploy body is empty. Any field is a 400 unknown_field: Yard deploys what the source says now. To roll back, change the source — git revert and push, an older image tag, or an older URL.

Caddy#

GET /api/v1/apps/{name}/caddy answers the app’s site file as text. It is empty when the app has no site. PUT takes the whole file as the body. Yard saves it and loads Caddy, and the answer lists the site’s hosts. An empty body removes the site.

Caddy checks the whole config before it serves a change. A refused file is a 400 bad_caddyfile with Caddy’s error, and the old file stays. A body that is not UTF-8 is a 400 bad_caddyfile too. A file over 64 KiB is a 400 too_large. When Caddy does not answer, the code is 502 caddy.

Prune#

POST /api/v1/prune removes the localhost/ images that no container uses, except localhost/yard-apply: each app keeps its running image and its 3 newest images, and an image older than days goes even among those 3. Then Podman’s image prune --external removes the untagged build images older than days. days is 1 or more, 7 by default, and dry is true or false; anything else is a 400 bad_json.

images is [{tag, bytes, kept}]. kept holds Podman’s reason when it refused to remove the image, else it is empty. freed is how much the image store shrank; a dry run reports 0. untagged counts the untagged images removed. On a dry run it counts the ones found, a minimum, because Podman’s prune also removes the parents that it leaves untagged. untagged_error holds Podman’s reason when its prune stopped part way.

Logs and events#

GET /api/v1/logs reads one container’s journal. container is required: a name, a 12-character id, or a full id; anything else is a 400. lines is 1 to 10000, 100 by default, and counts the entries read before filters. since and until take -30s, -15m, -1h, -2d, a date like 2025-01-31, or a time like 2025-01-31 14:00. follow=1 streams and ignores since, until, and after. A bad container is a 400 bad_container, a bad lines a 400 bad_lines, and a bad since or until a 400 bad_time; the events route answers the same codes.

hide and only filter on the host, each repeatable. A field rule is key=value or key!=value (a * glob) and key>n or key<n on a JSON record — the key reads the top level first, then attributes; anything else is a substring glob on the message. Lines that share a trace_id keep or drop as one trace. A bad expression is a 400 bad_filter; no filters means the output is unchanged.

An Accept header that names application/json answers one page instead of text: {entries: [{cursor, container, time, message}], cursor}. The top-level cursor is the last entry’s cursor — even when filters hide it — or empty for an empty page. Pass it back as after, and the next call returns only the entries after it, the first lines of them. A poller resumes exactly where it stopped.

GET /api/v1/events merges Podman and Yard events into one timeline, read forward from a start, like podman events. The start is after, a row’s cursor, or since, which is the last hour when neither is given. The answer is the first lines rows from the start, oldest first. lines is 1 to 10000, 100 by default. Pass the cursor of the last row as after, and the next call returns only the rows after it. A poller reads every event once. When the filters drop rows, Yard reads on until it fills lines or reaches until or the end.

The timeline holds Podman’s container events (create, start, stop, kill, died, restart, remove, pause, unpause) and Yard’s own events. Podman’s sync, exec, and health_status events and the API access log stay out. follow=1 streams NDJSON: from now with no start, else every event from the start on. An event row omits empty keys:

{time, source, event, app, container, container_id, image, exit_code, oom, actor, sha, status, message, fields, cursor}

fields holds the remaining Yard event fields. No field carries a secret: an env change logs key names only.

Forges and repos#

A forge row is {name, host, connected, app_id, installations, last_delivery, last_check, public_key?, slug?, error?}. Each installation is {id, account, selection, settings_url}, and selection is all or selected. Origin adds public_key and GitHub adds slug. Keys and secrets never appear in a response.

GET /api/v1/forges reads the saved rows and asks no forge. POST /api/v1/forges/{name}/installations asks the forge for the app’s installations, saves them, and answers the row. error is present when the forge refused. yard forge setup calls it until the installation lands. The installation webhook saves the same answer.

PUT /api/v1/forges/{name} saves a forge app once the forge accepts its credentials. An unknown forge name is a 404 not_found, and a missing or empty field is a 400 bad_json. app in the answer is {name, events} from the forge, plus webhook_url on Origin and slug on GitHub. The GitHub values are checked first: an app ID that is not digits is a 400 bad_app, a key that is not an RSA PEM or is over 16 KiB a 400 bad_key, and a webhook secret under 32 characters a 400 bad_secret.

POST /api/v1/repos creates a private repo. name is an app name. forge is github or origin, and it defaults to the one connected forge. owner defaults to the one installation’s account. The repo in the answer is the new repo’s URL. The installation must cover all repositories, on GitHub and on Origin: a “selected” installation cannot see the repo it makes. A separate account for generated apps keeps your other repos out of that installation.

Errors: 400 bad_json for a body that is not {name: str, owner?: str, forge?: str}, 400 bad_name, 400 forge_required when both forges are connected and forge is missing, 400 owner_required when several installations exist and owner is missing (the help names the accounts), 403 repo_permission — an installation on selected repos only, the missing Repository creation permission on GitHub, or the missing namespace:repositories:create scope on Origin — 404 no_installation when no installation owns owner, 409 repo_exists when owner/name is taken, 404 not_found for an unknown forge, and 502 forge when no forge is connected or the named one is not.

POST /api/v1/repos/token answers a GitHub installation token for one repo, with contents write only, for one hour. Contents write includes read, so the same token clones, fetches, and pushes. expires_at is when it stops working; ask for a new token before each git command in long work. An app that makes apps uses it, so it holds no GitHub key. The repo.token event names the repo, never the token.

The token works with plain git over HTTPS. No gh is needed. username is always x-access-token, and the token is the password. Give it to git through a credential helper, so it stays out of the command line and out of .git/config. The same helper works for clone, fetch, pull, and push:

YARD_GIT_TOKEN="$token" git -c credential.helper='!f() { echo username=x-access-token; echo "password=$YARD_GIT_TOKEN"; }; f' clone https://github.com/org/heldso.git

Yard fetches with its own token the same way.

Errors: 400 bad_json for a body that is not {repo: str}, 400 bad_repo for a repo that is not a full https URL, 403 token_permission when the installation cannot see the repo or lacks contents write, 404 no_installation when no installation owns the repo, 501 token_unsupported on Origin, and 502 forge when the forge is not connected.