{
  "components": {
    "schemas": {
      "AccessInfo": {
        "properties": {
          "role": {
            "description": "`view`, `operate` or `admin`: each includes the ones before.",
            "type": "string"
          },
          "setup": {
            "description": "Whether an admin may set the server up over the network.",
            "type": "boolean"
          },
          "subject": {
            "description": "Whose access token it is, when it is one.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "role",
          "setup"
        ],
        "type": "object"
      },
      "Act": {
        "description": "What running an action is given.",
        "properties": {
          "arguments": {
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "cols": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "input_b64": {
            "description": "Bytes for the standard input of an action that takes them, in base64:\nthe build context of a rookery for `upgrade-server source=here`. They\ngo over HTTP when they are more than the portal carries.",
            "type": [
              "string",
              "null"
            ]
          },
          "rows": {
            "description": "The size of the terminal, for an action that runs in one.",
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "sudo_password": {
            "description": "The SSH user's sudo password, for an action that logs in to a host\nwhose sudo asks for one. It is neither shown nor kept.",
            "type": [
              "string",
              "null"
            ]
          },
          "token": {
            "description": "Any text of the caller's. The same token again for the same subject\nand action answers with the job the first call started.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "Acted": {
        "description": "What running an action answers: one of the three.",
        "properties": {
          "job": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/JobInfo",
                "description": "The job that runs it, for an action of rookery that changes something."
              },
              {
                "type": "null"
              }
            ]
          },
          "result": {
            "description": "What an action that answers at once and changes nothing said."
          },
          "session": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Session",
                "description": "The session on the host, for an action the host runs."
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "Action": {
        "description": "Something that can be done to a subject: a host, the installation, and\nlater a provisioner or a resource. It says enough to build a form from.",
        "properties": {
          "arguments": {
            "items": {
              "$ref": "#/components/schemas/Argument"
            },
            "type": "array"
          },
          "available": {
            "description": "False, with `why`, when the subject's state rules it out now.",
            "type": "boolean"
          },
          "changes": {
            "description": "False when it only reads, and may be called at any time.",
            "type": "boolean"
          },
          "collection": {
            "description": "The id of the provisioner's collection it belongs to, whose items it\nmakes, acts on or lists. The screens offer it there and not on the\nprovisioner's page.",
            "type": "string"
          },
          "confirm": {
            "description": "The question to answer yes to before it runs.",
            "type": [
              "string",
              "null"
            ]
          },
          "group": {
            "description": "The group of the page it is listed in; `Host` when empty.",
            "type": "string"
          },
          "help": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/Role",
            "description": "The least role that may run it."
          },
          "runs": {
            "$ref": "#/components/schemas/Runs"
          },
          "steps": {
            "description": "What plugins add to it, in the order they run.",
            "items": {
              "$ref": "#/components/schemas/ActionStep"
            },
            "type": "array"
          },
          "terminal": {
            "description": "It needs a terminal session attached; only a host runs these.",
            "type": "boolean"
          },
          "why": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "ActionStep": {
        "description": "What a plugin adds to an action: a step run after it in the same run.",
        "properties": {
          "help": {
            "type": "string"
          },
          "label": {
            "type": "string"
          }
        },
        "required": [
          "label"
        ],
        "type": "object"
      },
      "Applied": {
        "description": "What rookery recorded on a host when it applied the configuration: its own\nversion, the plugins whose features the host has, and the provisioners\nthose features offer.",
        "properties": {
          "offers": {
            "items": {
              "$ref": "#/components/schemas/Offer"
            },
            "type": "array"
          },
          "plugins": {
            "items": {
              "$ref": "#/components/schemas/AppliedPlugin"
            },
            "type": "array"
          },
          "rookery": {
            "type": "string"
          },
          "tailnet": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TailnetDevice",
                "description": "The host's device on the tailnet, as its Tailscale client saw it at\nthe end of the apply, when it is on one."
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "rookery"
        ],
        "type": "object"
      },
      "AppliedPlugin": {
        "description": "A plugin as it was when a host's configuration was applied.",
        "properties": {
          "digest": {
            "description": "SHA-256 of its files, so a change without a new version shows too.",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "package": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "package",
          "version",
          "digest"
        ],
        "type": "object"
      },
      "Argument": {
        "properties": {
          "choices": {
            "description": "A command whose lines are the values to offer.",
            "type": "string"
          },
          "confirm": {
            "description": "For a yes or no: the question to answer yes to before the action\nruns with it on, instead of the action's own.",
            "type": "string"
          },
          "default": {
            "type": "string"
          },
          "fixed": {
            "description": "Why it keeps its default here and cannot be given another value,\nsuch as destroying a machine no provisioner made. The screens show\nit greyed and say this instead of changing it. Empty when it can be\nchanged.",
            "type": "string"
          },
          "help": {
            "description": "What it is for, in a sentence or two, beside its short label.",
            "type": "string"
          },
          "kind": {
            "description": "`resource` for an argument of a provisioner that sizes the machine:\nits CPUs, memory or disk. `text` for one whose value has several\nlines. `boolean` for a yes or no, which the screens show as a switch.\nEmpty for any other argument.",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "required": {
            "type": "boolean"
          },
          "secret": {
            "description": "What is given is a secret, such as a password: it is not shown as it\nis typed, nor kept, nor written to a job's output.",
            "type": "boolean"
          },
          "values": {
            "description": "The values a provisioner's argument takes, when it is a choice of a\nfew. Empty for one that takes any text.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "Behind": {
        "description": "How a host's configuration differs from what rookery would apply now.",
        "properties": {
          "changes": {
            "description": "rookery first when its version changed, then the plugins.",
            "items": {
              "$ref": "#/components/schemas/Change"
            },
            "type": "array"
          }
        },
        "required": [
          "changes"
        ],
        "type": "object"
      },
      "CallFrame": {
        "description": "rookeryd to the serving program.",
        "properties": {
          "body": {},
          "from": {
            "$ref": "#/components/schemas/From"
          },
          "id": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "method": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "method",
          "body",
          "from"
        ],
        "type": "object"
      },
      "Catalogue": {
        "properties": {
          "features": {
            "description": "What the server's plugins can install, in the order they are applied.",
            "items": {
              "$ref": "#/components/schemas/FeatureInfo"
            },
            "type": "array"
          },
          "template": {
            "description": "The profile a new host starts from."
          }
        },
        "required": [
          "template",
          "features"
        ],
        "type": "object"
      },
      "Change": {
        "description": "Something that changed since a host was applied: rookery itself or a plugin.",
        "properties": {
          "from": {
            "description": "The version the host was applied with.",
            "type": "string"
          },
          "id": {
            "description": "`rookery`, or a plugin's id.",
            "type": "string"
          },
          "to": {
            "description": "The version there is now; empty for a plugin that is gone, the same\nas `from` for one whose files changed.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "from",
          "to"
        ],
        "type": "object"
      },
      "Checked": {
        "properties": {
          "lines": {
            "description": "One line per thing checked, starting with ✓, ! or ✗.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "lines"
        ],
        "type": "object"
      },
      "Choices": {
        "properties": {
          "choices": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "choices"
        ],
        "type": "object"
      },
      "Collection": {
        "description": "A list of things a provisioner holds, such as the storage pools of a\nserver. Its items come with the provisioner's status, and its actions are\nthe provisioner's own: some make an item, some act on one item, whose\nkey fills their arguments, and some act on the whole list.",
        "properties": {
          "columns": {
            "description": "The values each item shows besides its name, in order.",
            "items": {
              "$ref": "#/components/schemas/CollectionColumn"
            },
            "type": "array"
          },
          "group": {
            "description": "The group of the provisioner's page it is listed in.",
            "type": "string"
          },
          "help": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "item": {
            "description": "The actions on one item.",
            "items": {
              "$ref": "#/components/schemas/CollectionAction"
            },
            "type": "array"
          },
          "key": {
            "description": "The names that identify an item, such as `pool` and `volume`. A\ncollection within another starts with that one's key.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "kinds": {
            "description": "The kinds of resource that are its items, such as `machine`, in\nplace of items the status gives: its item actions are offered on\nthe page of each resource of those kinds the provisioner made.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "label": {
            "description": "What one item is called, such as `Storage pool`.",
            "type": "string"
          },
          "list": {
            "description": "The actions on the whole list, such as pruning.",
            "items": {
              "$ref": "#/components/schemas/CollectionAction"
            },
            "type": "array"
          },
          "new": {
            "description": "The actions that make a new item.",
            "items": {
              "$ref": "#/components/schemas/CollectionAction"
            },
            "type": "array"
          },
          "plural": {
            "description": "What several are called, such as `Storage pools`.",
            "type": "string"
          },
          "remove": {
            "description": "The item action that removes one.",
            "type": "string"
          },
          "show": {
            "description": "The action that prints the list for the command line, which the\nscreens show as the table instead.",
            "type": "string"
          },
          "within": {
            "description": "The collection whose items hold these, such as the pools that hold\nvolumes. Each item of that one lists those that belong to it.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "key"
        ],
        "type": "object"
      },
      "CollectionAction": {
        "description": "An action of a provisioner as one of a collection's.",
        "properties": {
          "action": {
            "description": "The provisioner's action, by its name.",
            "type": "string"
          },
          "arguments": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "The argument of the action each part of the key fills, where its\nname is not the part's own: `{\"volume\": \"name\"}`.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "label": {
            "description": "What it is called where its item is known already, such as `Grow`.\nThe action's own label when empty.",
            "type": "string"
          }
        },
        "required": [
          "action"
        ],
        "type": "object"
      },
      "CollectionColumn": {
        "description": "A value an item of a collection shows.",
        "properties": {
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CollectionItem": {
        "description": "One item of a collection, as the provisioner's status gives it.",
        "properties": {
          "columns": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "The value of each column, by its name.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "key": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "The value of each part of the collection's key.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "name": {
            "type": "string"
          },
          "unavailable": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "The item actions that cannot run on it, each with why not.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CommandLine": {
        "description": "A list of arguments, or one string for `sh -c`.",
        "oneOf": [
          {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          {
            "type": "string"
          }
        ]
      },
      "Config": {
        "description": "`/etc/rookery/rookeryd.json`.",
        "properties": {
          "agent": {
            "default": "agent",
            "description": "The agent account.",
            "type": "string"
          },
          "agent_env": {
            "default": "/usr/local/bin/agent-env",
            "description": "A wrapper that gives the agent its environment.",
            "type": "string"
          },
          "operator": {
            "default": "",
            "description": "The SSH user.",
            "type": "string"
          },
          "roots": {
            "default": [],
            "description": "Folders the file calls may touch.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "simulated": {
            "default": false,
            "description": "Whether the host is simulated: in single-user mode its commands then\nrun through `agent_env` too, and its version says so.",
            "type": "boolean"
          },
          "systemd": {
            "default": null,
            "description": "Whether the calls that need systemd work. Off in single-user mode\nunless set.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "units": {
            "default": [],
            "description": "Units whose state the stats report.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "Created": {
        "description": "What creating a resource answers: its record and the job that makes it.",
        "properties": {
          "job": {
            "$ref": "#/components/schemas/JobInfo"
          },
          "resource": {
            "$ref": "#/components/schemas/Resource"
          }
        },
        "required": [
          "resource",
          "job"
        ],
        "type": "object"
      },
      "Credentials": {
        "description": "The passwords rookery generated for a host's accounts.",
        "properties": {
          "credentials": {
            "additionalProperties": {},
            "description": "The password of each account, by the account's name.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "required": [
          "credentials"
        ],
        "type": "object"
      },
      "Detail": {
        "description": "A row of what a provisioner says, shown as it is given.",
        "properties": {
          "label": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        },
        "required": [
          "label"
        ],
        "type": "object"
      },
      "Done": {
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "type": "object"
      },
      "Endpoint": {
        "description": "Where a resource can be reached: an address and a port, as its\nprovisioner reports it. The address is as seen from the machine the\nprovisioner's engine runs on, such as a Docker engine or an Incus server.",
        "properties": {
          "address": {
            "description": "An IP address or a DNS name.",
            "type": "string"
          },
          "hint": {
            "description": "What speaks there, for people, such as `http` or `postgres`.",
            "type": "string"
          },
          "local": {
            "description": "The engine runs on the server's own machine, so the address is one\nthe server reaches as it is, a loopback address among them.",
            "type": "boolean"
          },
          "name": {
            "description": "Unique among the resource's endpoints: lowercase letters, digits, `-`, `_` and `.`.",
            "type": "string"
          },
          "port": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "protocol": {
            "description": "`tcp` or `udp`.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "address",
          "port",
          "protocol"
        ],
        "type": "object"
      },
      "ErrorBody": {
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ErrorDetail": {
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "message"
        ],
        "type": "object"
      },
      "FeatureInfo": {
        "description": "Something a plugin installs, for the Features page of a host.",
        "properties": {
          "group": {
            "description": "The group of the Features page it is listed in.",
            "type": "string"
          },
          "help": {
            "type": "string"
          },
          "key": {
            "description": "`PLUGIN/FEATURE`, as a profile's `rookery_plugin_features` names it.",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "types": {
            "description": "The types of host it is for, such as `workstation` or `node`.",
            "items": {
              "$ref": "#/components/schemas/HostType"
            },
            "type": "array"
          }
        },
        "required": [
          "key",
          "label",
          "group",
          "help",
          "types"
        ],
        "type": "object"
      },
      "FileEntry": {
        "properties": {
          "kind": {
            "description": "`file`, `dir`, `link` or `other`.",
            "type": "string"
          },
          "modified": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "size": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "name",
          "kind",
          "size",
          "modified"
        ],
        "type": "object"
      },
      "Filesystem": {
        "properties": {
          "available": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "device": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "mount": {
            "type": "string"
          },
          "total": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "used": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "mount",
          "device",
          "kind",
          "total",
          "used",
          "available"
        ],
        "type": "object"
      },
      "From": {
        "description": "Who did something, as rookeryd saw it.",
        "properties": {
          "level": {
            "$ref": "#/components/schemas/Level"
          },
          "session": {
            "type": [
              "string",
              "null"
            ]
          },
          "uid": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "level",
          "uid"
        ],
        "type": "object"
      },
      "Generate": {
        "description": "Something for the server to make up for a profile.",
        "properties": {
          "host": {
            "type": [
              "string",
              "null"
            ]
          },
          "password": {
            "description": "For `password`: the password to hash. Without it one is made up and\nkept in the server's store with `host`, under `user`, for\n`hosts.credentials` to give.",
            "type": [
              "string",
              "null"
            ]
          },
          "user": {
            "type": [
              "string",
              "null"
            ]
          },
          "what": {
            "description": "`hostname` or `password`.",
            "type": "string"
          }
        },
        "required": [
          "what"
        ],
        "type": "object"
      },
      "Generated": {
        "properties": {
          "note": {
            "description": "What to tell whoever asked.",
            "type": "string"
          },
          "password": {
            "description": "A password that was made up, for whoever asked to write down.",
            "type": [
              "string",
              "null"
            ]
          },
          "value": {
            "description": "The host name or the password's hash.",
            "type": "string"
          }
        },
        "required": [
          "value",
          "note"
        ],
        "type": "object"
      },
      "Gpu": {
        "properties": {
          "memory_total": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "memory_used": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "utilization": {
            "description": "Percent.",
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "name",
          "utilization",
          "memory_used",
          "memory_total"
        ],
        "type": "object"
      },
      "HostAction": {
        "description": "An action of the host's controller: an entry of `/etc/rookery/actions.json`.\nListed without `run`.",
        "properties": {
          "agent": {
            "description": "The agent may run it.",
            "type": "boolean"
          },
          "arguments": {
            "items": {
              "$ref": "#/components/schemas/Argument"
            },
            "type": "array"
          },
          "confirm": {
            "type": [
              "string",
              "null"
            ]
          },
          "extends": {
            "description": "Actions it is a step of; it then has no row of its own.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "group": {
            "type": "string"
          },
          "help": {
            "type": "string"
          },
          "input": {
            "description": "What the workstation sends on standard input: `secrets`.",
            "type": [
              "string",
              "null"
            ]
          },
          "label": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "run": {
            "type": "string"
          },
          "terminal": {
            "type": "boolean"
          },
          "user": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "HostBehind": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Behind"
          },
          {
            "properties": {
              "name": {
                "type": "string"
              }
            },
            "required": [
              "name"
            ],
            "type": "object"
          }
        ],
        "description": "A host whose configuration is behind, and how."
      },
      "HostInfo": {
        "properties": {
          "address": {
            "description": "Its SSH address.",
            "type": "string"
          },
          "api": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "applied": {
            "description": "The rookery version its configuration was last applied with, when its\nrookeryd says, which it does for a host applied since.",
            "type": [
              "string",
              "null"
            ]
          },
          "behind": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Behind",
                "description": "What changed since then, when the server would apply something else now."
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "description": "Why it is not reachable.",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "description": "Its id, which stays when it is renamed; empty for a host that is not saved.",
            "type": "string"
          },
          "machine": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/HostMachine",
                "description": "The machine a provisioner made for it, or one planned for it."
              },
              {
                "type": "null"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "power": {
            "$ref": "#/components/schemas/Power",
            "description": "Whether rookery can start and stop it, and whether it runs: running\nwhen its controller answers, else as its provisioner said last."
          },
          "reachable": {
            "type": "boolean"
          },
          "rotating": {
            "description": "A rotation of a key it logs in with is not done on it yet.",
            "type": "boolean"
          },
          "seen": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/HostType",
                "description": "The type it was seen to be: what its controller's record says, `ssh`\nwhen rookery logged in and found no controller. Absent when it could\nnot be asked."
              },
              {
                "type": "null"
              }
            ]
          },
          "type": {
            "$ref": "#/components/schemas/HostType",
            "description": "The type its profile means it to be."
          },
          "version": {
            "description": "The version of its rookeryd.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "name",
          "address",
          "reachable",
          "type",
          "power"
        ],
        "type": "object"
      },
      "HostMachine": {
        "description": "The machine of a host, as rookery's record of the resource has it.",
        "properties": {
          "external_id": {
            "description": "The provisioner's id of it; empty until it is made.",
            "type": "string"
          },
          "provisioner": {
            "description": "The provisioner that made it, or is to make it.",
            "type": "string"
          },
          "resource": {
            "description": "rookery's id of the resource.",
            "type": "string"
          },
          "state": {
            "description": "As last seen, or `planned` for one not asked for yet.",
            "type": "string"
          }
        },
        "required": [
          "resource",
          "provisioner",
          "external_id",
          "state"
        ],
        "type": "object"
      },
      "HostType": {
        "description": "What rookery does with a host: what its profile means it to be, or what it\nwas seen to be. They are in the order of how much of rookery each has.",
        "enum": [
          "ssh",
          "managed",
          "node",
          "workstation"
        ],
        "type": "string"
      },
      "Inbox": {
        "properties": {
          "messages": {
            "items": {
              "$ref": "#/components/schemas/InboxMessage"
            },
            "type": "array"
          },
          "next": {
            "description": "Pass as `before` for older ones, when there are more.",
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "messages"
        ],
        "type": "object"
      },
      "InboxMessage": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Message"
          },
          {
            "properties": {
              "done": {
                "type": "boolean"
              },
              "host": {
                "description": "The host's name.",
                "type": "string"
              },
              "host_id": {
                "description": "The host's id, when it is a saved host.",
                "type": "string"
              },
              "seq": {
                "description": "The order it was taken in; what `before` counts in.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "host",
              "done",
              "seq"
            ],
            "type": "object"
          }
        ],
        "description": "A stored message: the host's message with where it came from."
      },
      "Input": {
        "properties": {
          "data_b64": {
            "type": [
              "string",
              "null"
            ]
          },
          "eof": {
            "description": "Close a process's standard input.",
            "type": "boolean"
          },
          "text": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "Interface": {
        "properties": {
          "name": {
            "type": "string"
          },
          "rx_bytes": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "tx_bytes": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "name",
          "rx_bytes",
          "tx_bytes"
        ],
        "type": "object"
      },
      "JobInfo": {
        "description": "A job of rookery: one run of an action, with its output kept where it ran.",
        "properties": {
          "action": {
            "description": "The action it runs, such as `apply`, `rollout` or `provision`.",
            "type": "string"
          },
          "arguments": {
            "description": "What it was started with, as people may see it: the command of a\nresource's `exec`, or an action's arguments as `NAME=VALUE`. Never a\nsecret argument, a password or standard input.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "ended": {
            "type": [
              "string",
              "null"
            ]
          },
          "exit_code": {
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "host": {
            "description": "The hosts it is about, for a reader: a name, or several with commas.",
            "type": "string"
          },
          "host_id": {
            "description": "The ids of those hosts, as `host` lists them; a host in a file by its path.",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "report": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RolloutReport",
                "description": "How a roll-out went, host by host, once it has ended."
              },
              {
                "type": "null"
              }
            ]
          },
          "started": {
            "type": "string"
          },
          "stopped_by": {
            "description": "Who stopped it before it ended by itself.",
            "type": [
              "string",
              "null"
            ]
          },
          "subject": {
            "description": "What it was done to, by id: `host:ID`, `provisioner:ID`,\n`resource:ID` or `installation`. Empty for a job recorded without one.",
            "type": "string"
          },
          "subject_name": {
            "description": "What it was done to, by name as it is called now: `host:NAME`,\n`provisioner:NAME`, `resource:ID` or `installation`; by id for one\nthat is gone.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "started"
        ],
        "type": "object"
      },
      "Keep": {
        "enum": [
          "none",
          "last",
          "log"
        ],
        "type": "string"
      },
      "KeptProfile": {
        "description": "The profile a host keeps of itself, at `/etc/rookery/profile.json`: the\nprofile as rookery holds it, without the enrollment key and without its\n`access`, how the rookery that wrote it reaches the host. A rookery that does\nnot have the host can take it over from this.",
        "properties": {
          "format": {
            "description": "The format of this document.",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "host": {
            "description": "The name the host has in the rookery that wrote it.",
            "type": "string"
          },
          "instance": {
            "description": "The same in a document of format 1."
          },
          "machine": {
            "description": "The record of the machine rookery created for the host, as a resource,\nwhen it did."
          },
          "profile": {
            "description": "The profile."
          },
          "rookery": {
            "description": "The version of the rookery that wrote it.",
            "type": "string"
          },
          "written": {
            "description": "When it was written, in RFC 3339.",
            "type": "string"
          }
        },
        "required": [
          "format",
          "rookery",
          "host",
          "profile"
        ],
        "type": "object"
      },
      "KeyInfo": {
        "description": "A key of the ring, by its public half.",
        "properties": {
          "fingerprint": {
            "description": "Its SHA256 fingerprint, as `ssh-keygen -l` shows it.",
            "type": "string"
          },
          "hosts": {
            "description": "The server's hosts that log in with it.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "id": {
            "description": "Its id; empty for the key that replaces another while it rotates.",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "pending": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/KeyInfo",
                "description": "The key replacing it while a rotation runs."
              },
              {
                "type": "null"
              }
            ]
          },
          "public": {
            "description": "The public half, a line of `authorized_keys`.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "public",
          "fingerprint"
        ],
        "type": "object"
      },
      "KeyList": {
        "properties": {
          "keys": {
            "items": {
              "$ref": "#/components/schemas/KeyInfo"
            },
            "type": "array"
          }
        },
        "required": [
          "keys"
        ],
        "type": "object"
      },
      "KvEntry": {
        "properties": {
          "key": {
            "type": "string"
          },
          "revision": {
            "format": "int64",
            "type": "integer"
          },
          "updated": {
            "type": "string"
          },
          "value": {}
        },
        "required": [
          "key",
          "value",
          "revision",
          "updated"
        ],
        "type": "object"
      },
      "KvList": {
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/components/schemas/KvEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "entries"
        ],
        "type": "object"
      },
      "KvWritten": {
        "properties": {
          "key": {
            "type": "string"
          },
          "revision": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "key",
          "revision"
        ],
        "type": "object"
      },
      "Level": {
        "enum": [
          "host",
          "agent"
        ],
        "type": "string"
      },
      "ListedResource": {
        "description": "What a provisioner lists of what it holds, beside rookery's records.",
        "properties": {
          "host": {
            "description": "The host a machine was made for, when it says.",
            "type": "string"
          },
          "id": {
            "description": "The provisioner's id of it; empty for a record whose `create` did not end.",
            "type": "string"
          },
          "kind": {
            "description": "`machine`, or a kind the plugin names, such as `deployment`.",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "resource": {
            "description": "rookery's id of it, when rookery has a record of it. One the provisioner\nlists without one is not rookery's, or rookery lost track of it.",
            "type": "string"
          },
          "state": {
            "description": "What the provisioner's list says, or empty when it was not asked.",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "name"
        ],
        "type": "object"
      },
      "Listing": {
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/components/schemas/FileEntry"
            },
            "type": "array"
          },
          "path": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "entries"
        ],
        "type": "object"
      },
      "LogEntry": {
        "properties": {
          "cursor": {
            "description": "Give it back as `since` to go on from here.",
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "priority": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "time": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "time",
          "unit",
          "priority",
          "message",
          "cursor"
        ],
        "type": "object"
      },
      "Memory": {
        "properties": {
          "available": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "total": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "used": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "total",
          "used",
          "available"
        ],
        "type": "object"
      },
      "Message": {
        "properties": {
          "body": {},
          "from": {
            "$ref": "#/components/schemas/From"
          },
          "id": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "keep": {
            "$ref": "#/components/schemas/Keep"
          },
          "time": {
            "type": "string"
          },
          "topic": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "topic",
          "body",
          "keep",
          "from",
          "time"
        ],
        "type": "object"
      },
      "Messages": {
        "properties": {
          "messages": {
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "type": "array"
          },
          "next": {
            "description": "Pass as `since` for the rest, when there is more.",
            "format": "int64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "messages"
        ],
        "type": "object"
      },
      "Method": {
        "properties": {
          "description": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "Named": {
        "description": "A thing rookery keeps, by its id and its name.",
        "properties": {
          "id": {
            "description": "Its id, which stays when it is renamed.",
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name"
        ],
        "type": "object"
      },
      "NewResource": {
        "description": "What to create a resource with.",
        "properties": {
          "arguments": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values of the provisioner's and the kind's arguments; the others\ntake their settings or defaults.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "host": {
            "description": "The saved host a machine is made for, and set up as.",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "description": "`machine` when empty.",
            "type": "string"
          },
          "name": {
            "description": "The host's name for a host's machine when empty.",
            "type": "string"
          },
          "provisioner": {
            "description": "The provisioner, by name or id.",
            "type": "string"
          },
          "secrets": {
            "items": {
              "$ref": "#/components/schemas/ResourceSecret"
            },
            "type": "array"
          },
          "spec": {
            "description": "The specification, for a kind that has one, as its plugin reads it.",
            "type": [
              "string",
              "null"
            ]
          },
          "token": {
            "description": "Any text of the caller's. The same token again answers with the\nresource and the job the first call started.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "provisioner"
        ],
        "type": "object"
      },
      "Offer": {
        "description": "Provisioners a feature of a host offers, as its tasks found them: rookery\nregisters each under a name of its own that names the host. The host\nserves this to anyone who may read it, so it holds public values only,\nsuch as a server's certificate, never a key.",
        "properties": {
          "aliases": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "description": "Other values of a setting that reach the same server, such as the\nname a rookery server on the host gives it: a provisioner registered by\nhand with one of them is named to its owner, who can make it the\nhost's.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "feature": {
            "description": "The feature, as `PLUGIN/FEATURE`.",
            "type": "string"
          },
          "fingerprint": {
            "description": "What the host says identifies the server, such as the fingerprint of\nits certificate, for the person who reads the report.",
            "type": "string"
          },
          "provisioners": {
            "description": "The plugin's provisioners it offers, by their ids in the plugin.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "secrets": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values of the provisioners' secrets, such as the certificate of the\nserver to pin, kept as the provisioners' own.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "settings": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values of the provisioners' own arguments. `{address}`, `{user}` and\n`{port}` stand for where rookery reaches the host and as whom.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "required": [
          "feature",
          "provisioners"
        ],
        "type": "object"
      },
      "Output": {
        "properties": {
          "data_b64": {
            "type": "string"
          },
          "ended": {
            "description": "Nothing more will come.",
            "type": "boolean"
          },
          "first_offset": {
            "description": "Where what is still kept begins, when the start was dropped.",
            "format": "int64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "lines": {
            "description": "The same as text, when read by lines.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "next_line": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "next_offset": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "offset": {
            "description": "The offset this answer starts at.",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "data_b64",
          "offset",
          "next_offset",
          "next_line",
          "ended"
        ],
        "type": "object"
      },
      "PluginAction": {
        "description": "An action a feature adds to a host.",
        "properties": {
          "agent": {
            "description": "The agent may run it with `box run`.",
            "type": "boolean"
          },
          "arguments": {
            "description": "The names of the arguments it asks for.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "extends": {
            "description": "Actions of rookery it runs after, with no row of its own.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "label": {
            "type": "string"
          },
          "name": {
            "description": "The action is `PLUGIN:NAME` on the host.",
            "type": "string"
          },
          "user": {
            "description": "`agent`, `operator` or `root`.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "label",
          "user"
        ],
        "type": "object"
      },
      "PluginFeature": {
        "description": "Something a plugin installs, switched on per host.",
        "properties": {
          "actions": {
            "items": {
              "$ref": "#/components/schemas/PluginAction"
            },
            "type": "array"
          },
          "channels": {
            "description": "Channel topics, without the plugin's id.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "group": {
            "description": "The group of the Features page it is listed in.",
            "type": "string"
          },
          "help": {
            "type": "string"
          },
          "id": {
            "description": "A profile names it `PLUGIN/ID`.",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "services": {
            "items": {
              "$ref": "#/components/schemas/PluginService"
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "label",
          "group"
        ],
        "type": "object"
      },
      "PluginInfo": {
        "description": "A plugin that was found, with what it can install.",
        "properties": {
          "description": {
            "type": "string"
          },
          "dir": {
            "description": "Where it is on the machine that has it.",
            "type": "string"
          },
          "features": {
            "items": {
              "$ref": "#/components/schemas/PluginFeature"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "origin": {
            "$ref": "#/components/schemas/PluginOrigin"
          },
          "package": {
            "description": "Its npm name.",
            "type": "string"
          },
          "provisioners": {
            "description": "What it can create machines with.",
            "items": {
              "$ref": "#/components/schemas/ProvisionerInfo"
            },
            "type": "array"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "label",
          "package",
          "version",
          "origin",
          "dir"
        ],
        "type": "object"
      },
      "PluginList": {
        "description": "The plugins a rookery serve has, and where it keeps its own.",
        "properties": {
          "dir": {
            "description": "The directory of its own plugins; a folder copied there is one too.",
            "type": "string"
          },
          "plugins": {
            "items": {
              "$ref": "#/components/schemas/PluginInfo"
            },
            "type": "array"
          }
        },
        "required": [
          "plugins",
          "dir"
        ],
        "type": "object"
      },
      "PluginOrigin": {
        "description": "Where a plugin comes from, which says whether it can be removed.",
        "enum": [
          "shipped",
          "npm",
          "folder"
        ],
        "type": "string"
      },
      "PluginReport": {
        "description": "What npm said of a change, a few lines; the first starts with ✓.",
        "properties": {
          "behind": {
            "description": "After an update: the hosts whose configuration is now behind.",
            "items": {
              "$ref": "#/components/schemas/HostBehind"
            },
            "type": "array"
          },
          "lines": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "lines"
        ],
        "type": "object"
      },
      "PluginService": {
        "description": "A program a feature keeps running on the host to answer calls.",
        "properties": {
          "methods": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "description": "The service is `PLUGIN/NAME` on the host.",
            "type": "string"
          },
          "user": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "user"
        ],
        "type": "object"
      },
      "PluginSpec": {
        "description": "What npm installs, with the server's npm configuration and none of the\npackage's scripts.",
        "properties": {
          "spec": {
            "description": "A package of the server's npm registry, `[@SCOPE/]NAME[@VERSION]`, or\nthe https address of a .tgz.",
            "type": "string"
          }
        },
        "required": [
          "spec"
        ],
        "type": "object"
      },
      "PluginUpdate": {
        "description": "Whether a newer version of a plugin is there, as its registry says.",
        "properties": {
          "id": {
            "type": "string"
          },
          "latest": {
            "description": "The registry's latest version, when it is another one.",
            "type": [
              "string",
              "null"
            ]
          },
          "note": {
            "description": "Why there is nothing to ask, or what asking said: a plugin from a\n.tgz or a folder has no registry to ask.",
            "type": "string"
          },
          "package": {
            "type": "string"
          },
          "version": {
            "description": "The version installed.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "package",
          "version"
        ],
        "type": "object"
      },
      "PluginUpdateSpec": {
        "description": "What to update: one plugin by its id or npm name, or all of them.",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "PluginUpdates": {
        "description": "The answer of `plugins.check`: each of the user's plugins.",
        "properties": {
          "plugins": {
            "items": {
              "$ref": "#/components/schemas/PluginUpdate"
            },
            "type": "array"
          }
        },
        "required": [
          "plugins"
        ],
        "type": "object"
      },
      "Power": {
        "description": "How a host is started and stopped, and whether it runs. A host a\nprovisioner made is started and stopped through it, when its kind can;\nany other declares in its profile's `power` how it is stopped.",
        "properties": {
          "start": {
            "description": "Whether rookery can start it.",
            "type": "boolean"
          },
          "start_by": {
            "description": "What starts it: `provisioner`, or empty when nothing does.",
            "type": "string"
          },
          "state": {
            "$ref": "#/components/schemas/PowerState",
            "description": "Whether it runs: what its controller or its provisioner said last."
          },
          "stop": {
            "description": "Whether rookery can stop it.",
            "type": "boolean"
          },
          "stop_by": {
            "description": "What stops it: `provisioner`, `controller`, or empty when nothing does.",
            "type": "string"
          }
        },
        "required": [
          "start",
          "stop",
          "state"
        ],
        "type": "object"
      },
      "PowerState": {
        "description": "Whether a host runs, as far as the server knows.",
        "enum": [
          "running",
          "stopped",
          "unknown"
        ],
        "type": "string"
      },
      "Process": {
        "properties": {
          "command": {
            "type": "string"
          },
          "cpu_time": {
            "description": "Seconds of CPU used so far.",
            "format": "double",
            "type": "number"
          },
          "memory": {
            "description": "Resident memory in bytes.",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "parent": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "pid": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "user": {
            "type": "string"
          }
        },
        "required": [
          "pid",
          "parent",
          "user",
          "command",
          "cpu_time",
          "memory"
        ],
        "type": "object"
      },
      "ProvisionerInfo": {
        "description": "Something a plugin creates machines with, for a saved host's profile.",
        "properties": {
          "actions": {
            "description": "Its plugin's own actions, such as listing images or pruning.",
            "items": {
              "$ref": "#/components/schemas/Action"
            },
            "type": "array"
          },
          "arguments": {
            "description": "What creating a machine takes: the provisioner's own arguments first,\nthen those of its machines.",
            "items": {
              "$ref": "#/components/schemas/Argument"
            },
            "type": "array"
          },
          "collections": {
            "description": "What it holds that can be listed, such as storage pools, each with\nthe actions of its items.",
            "items": {
              "$ref": "#/components/schemas/Collection"
            },
            "type": "array"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "description": "Its id, which stays when it is renamed. In the list of types, the\ntype itself.",
            "type": "string"
          },
          "kinds": {
            "description": "What it can make: `machine`, and kinds its plugin names.",
            "items": {
              "$ref": "#/components/schemas/ProvisionerKind"
            },
            "type": "array"
          },
          "label": {
            "type": "string"
          },
          "missing_secrets": {
            "description": "The required ones that have no value. Not looked at in a plugin's listing.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "description": "The name it is registered under, such as `ovh-incus`. In the list of\ntypes, the type itself.",
            "type": "string"
          },
          "node": {
            "description": "The node it lives on, when a feature of that host offered it, by name.",
            "type": "string"
          },
          "node_id": {
            "description": "The id of that node.",
            "type": "string"
          },
          "own": {
            "description": "The names of the provisioner's own arguments, which say where it is,\nsuch as an Incus server. Their values are kept as its settings.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "problem": {
            "description": "Why it cannot be used here, as a sentence that says what to change.\nEmpty when it can.",
            "type": "string"
          },
          "secrets": {
            "description": "The rookery secrets it is given.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "settings": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "The values of its own arguments that are kept, by name.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "setup": {
            "description": "`seed`: the machine boots with rookery's cloud seed and sets itself up.\n`apply`: rookery applies the profile over SSH once the machine answers.",
            "type": "string"
          },
          "type": {
            "description": "The plugin's provisioner it is, as `PLUGIN/ID`, such as `incus/vm`.",
            "type": "string"
          },
          "verbs": {
            "description": "What it can do besides `create`, `status` and `destroy`: `start`,\n`stop`, `list`, `log`.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "label",
          "setup"
        ],
        "type": "object"
      },
      "ProvisionerKind": {
        "description": "A kind of thing a provisioner makes.",
        "properties": {
          "actions": {
            "description": "What its plugin can do to one, each run with the verb `act` and the\nresource's id.",
            "items": {
              "$ref": "#/components/schemas/Action"
            },
            "type": "array"
          },
          "arguments": {
            "items": {
              "$ref": "#/components/schemas/Argument"
            },
            "type": "array"
          },
          "id": {
            "description": "`machine`, or a kind the plugin names, such as `deployment`.",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "setup": {
            "description": "For a machine: `seed` or `apply`, as for the provisioner.",
            "type": "string"
          },
          "spec": {
            "description": "The specification one is made from, for a kind that has one: its\n`format` and `label`, as the plugin declares them."
          },
          "verbs": {
            "description": "What can be done to one besides `create`, `status` and `destroy`:\n`start`, `stop`, `change`, `logs`.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      },
      "ProvisionerState": {
        "description": "A provisioner's page: what it is, what it says of itself now, and what\nit holds.",
        "properties": {
          "collections": {
            "additionalProperties": {
              "items": {
                "$ref": "#/components/schemas/CollectionItem"
              },
              "type": "array"
            },
            "description": "The items of each of its collections, by the collection's id, as its\nstatus gave them.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "details": {
            "items": {
              "$ref": "#/components/schemas/Detail"
            },
            "type": "array"
          },
          "message": {
            "description": "What it said of itself, or why it could not be asked.",
            "type": "string"
          },
          "provisioner": {
            "$ref": "#/components/schemas/ProvisionerInfo"
          },
          "resources": {
            "description": "rookery's records of what it made, with what its own list says.",
            "items": {
              "$ref": "#/components/schemas/ListedResource"
            },
            "type": "array"
          },
          "state": {
            "description": "`ready`, `unreachable` or `unusable`, or what the provisioner said.",
            "type": "string"
          },
          "values": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "description": "The values an argument takes here, by its name, where the\nprovisioner narrows what it declares, such as the pools there are.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "required": [
          "provisioner",
          "state"
        ],
        "type": "object"
      },
      "Publish": {
        "properties": {
          "body": {},
          "keep": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Keep"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "type": "object"
      },
      "PublishFrame": {
        "description": "What a client sends over the channel stream to publish.",
        "properties": {
          "body": {},
          "keep": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Keep"
              },
              {
                "type": "null"
              }
            ]
          },
          "topic": {
            "type": "string"
          }
        },
        "required": [
          "topic"
        ],
        "type": "object"
      },
      "Registries": {
        "properties": {
          "registries": {
            "additionalProperties": {},
            "description": "By name: its `id`, `type` (nexus, npm, raw or docker), `url`,\n`username` and, for a Nexus server, its `repositories`. The id is\nrookery's, and is left out of what is saved.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          }
        },
        "required": [
          "registries"
        ],
        "type": "object"
      },
      "Rename": {
        "description": "A new name for a thing.",
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "ReplyFrame": {
        "description": "The serving program's answer.",
        "properties": {
          "error": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ErrorDetail"
              },
              {
                "type": "null"
              }
            ]
          },
          "id": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "result": {}
        },
        "required": [
          "id"
        ],
        "type": "object"
      },
      "Resize": {
        "properties": {
          "cols": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "rows": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "rows",
          "cols"
        ],
        "type": "object"
      },
      "Resource": {
        "description": "Something a provisioner made for rookery: a machine, which may be a\nhost's, or a kind its plugin names, such as a deployment.",
        "properties": {
          "address": {
            "type": "string"
          },
          "arguments": {
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "checked": {
            "description": "When its provisioner was last asked about it.",
            "type": "string"
          },
          "created": {
            "description": "When it was asked for, RFC 3339.",
            "type": "string"
          },
          "endpoints": {
            "description": "Where it can be reached, as its provisioner last said: when it was\nmade, changed or checked.",
            "items": {
              "$ref": "#/components/schemas/Endpoint"
            },
            "type": "array"
          },
          "external_id": {
            "description": "The provisioner's id of it; empty until `create` said it.",
            "type": "string"
          },
          "host": {
            "description": "The host a machine belongs to, if any, by name; a profile in a file\nby its path.",
            "type": [
              "string",
              "null"
            ]
          },
          "host_id": {
            "description": "The id of that host, when it is a saved host.",
            "type": "string"
          },
          "id": {
            "description": "rookery's id of it, stable for the life of the record.",
            "type": "string"
          },
          "kind": {
            "description": "`machine`, or a kind the plugin declares.",
            "type": "string"
          },
          "name": {
            "description": "Unique per provisioner and kind.",
            "type": "string"
          },
          "problem": {
            "description": "Why its state is `unknown`, or what is wrong with it.",
            "type": "string"
          },
          "provisioner": {
            "description": "The name of the provisioner that made it.",
            "type": "string"
          },
          "provisioner_id": {
            "description": "The id of that provisioner, when it is registered.",
            "type": "string"
          },
          "secrets": {
            "description": "The rookery secrets it is given, by name; never their values.",
            "items": {
              "$ref": "#/components/schemas/ResourceSecret"
            },
            "type": "array"
          },
          "spec_sha256": {
            "description": "The SHA-256 of its stored specification, for a kind that has one.",
            "type": "string"
          },
          "state": {
            "description": "`creating`, `running`, `stopped`, `missing` or `unknown`, as last\nseen; `planned` for a host's machine saved to be made later, as a\nduplicate's is.",
            "type": "string"
          },
          "verbs": {
            "description": "What can be done to it besides being removed: `start`, `stop`,\n`change`, `logs`, `exec`, as its kind declares.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "provisioner",
          "kind",
          "name",
          "state"
        ],
        "type": "object"
      },
      "ResourceChange": {
        "description": "What to change of a resource: what is given replaces what it had.",
        "properties": {
          "arguments": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values of the kind's arguments, over those it has.",
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "secrets": {
            "items": {
              "$ref": "#/components/schemas/ResourceSecret"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "spec": {
            "type": [
              "string",
              "null"
            ]
          },
          "token": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "ResourceSecret": {
        "description": "A rookery secret a resource is given in its environment, by name. Its\nvalue is resolved when the provisioner is called and never kept with\nthe resource.",
        "properties": {
          "env": {
            "description": "The environment variable it becomes; the secret's name when empty.",
            "type": "string"
          },
          "name": {
            "description": "The name of the rookery secret.",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "Role": {
        "description": "What a caller has to be allowed for an operation. Each role includes the\nones before it.",
        "enum": [
          "view",
          "operate",
          "admin"
        ],
        "type": "string"
      },
      "RolloutHost": {
        "properties": {
          "changes": {
            "description": "What had changed, as it was before applying.",
            "items": {
              "$ref": "#/components/schemas/Change"
            },
            "type": "array"
          },
          "error": {
            "description": "What went wrong, for a failed host.",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "rebooted": {
            "description": "It was rebooted.",
            "type": "boolean"
          },
          "state": {
            "$ref": "#/components/schemas/RolloutState"
          },
          "warnings": {
            "description": "What did not go well without being a failure, such as an update step\nthat ended badly. One stops the roll-out after this host.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "name",
          "state"
        ],
        "type": "object"
      },
      "RolloutReport": {
        "description": "The result of a roll-out, host by host in the order they were taken.",
        "properties": {
          "hosts": {
            "items": {
              "$ref": "#/components/schemas/RolloutHost"
            },
            "type": "array"
          },
          "ok": {
            "description": "Every host is done or current.",
            "type": "boolean"
          }
        },
        "required": [
          "hosts",
          "ok"
        ],
        "type": "object"
      },
      "RolloutState": {
        "description": "How one host of a roll-out went.",
        "enum": [
          "done",
          "current",
          "skipped",
          "failed"
        ],
        "type": "string"
      },
      "RunAction": {
        "properties": {
          "arguments": {
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "cols": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "input_b64": {
            "type": [
              "string",
              "null"
            ]
          },
          "rows": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "Runs": {
        "description": "Where an action runs.",
        "enum": [
          "rookery",
          "host"
        ],
        "type": "string"
      },
      "SavedProvisioner": {
        "description": "A provisioner to register, or the type and settings of one that is.",
        "properties": {
          "settings": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values of its own arguments, such as the server it uses. Empty ones\nare not kept. Left out, the settings it has stay.",
            "propertyNames": {
              "type": "string"
            },
            "type": [
              "object",
              "null"
            ]
          },
          "type": {
            "description": "The plugin's provisioner it is, as `PLUGIN/ID`. A registered one keeps\nits type: this is the same or empty.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "Screen": {
        "properties": {
          "cols": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "cursor_col": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "cursor_row": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "rows": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "rows",
          "cols",
          "text",
          "cursor_row",
          "cursor_col"
        ],
        "type": "object"
      },
      "SecretNames": {
        "description": "The names of the secrets the server keeps. Their values never leave it\nexcept to a host.",
        "properties": {
          "names": {
            "description": "The global secrets' names, and the addresses of those that belong to\nsomething: a registry's password or token is `registry/NAME`, the\npasswords rookery logs in to a host with `ssh/HOST` and `sudo/HOST`,\nand a provisioner's own `provisioner/NAME/SECRET`.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "secrets": {
            "description": "The global secrets, by name, with their ids.",
            "items": {
              "$ref": "#/components/schemas/Named"
            },
            "type": "array"
          }
        },
        "required": [
          "names",
          "secrets"
        ],
        "type": "object"
      },
      "SecretValue": {
        "properties": {
          "value": {
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "Service": {
        "properties": {
          "agent": {
            "type": "boolean"
          },
          "declared": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          },
          "methods": {
            "items": {
              "$ref": "#/components/schemas/Method"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "uid": {
            "description": "Who serves it now.",
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "up": {
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "description",
          "agent",
          "methods",
          "declared",
          "up"
        ],
        "type": "object"
      },
      "ServiceSpec": {
        "description": "An entry of `/etc/rookery/services.json`.",
        "properties": {
          "agent": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          },
          "methods": {
            "items": {
              "$ref": "#/components/schemas/Method"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "run": {
            "type": "string"
          },
          "timeout": {
            "description": "Seconds a call may take.",
            "format": "int64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "user": {
            "description": "`root` or `agent`.",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "Session": {
        "properties": {
          "action": {
            "description": "The action it was started for, if any.",
            "type": [
              "string",
              "null"
            ]
          },
          "cols": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "command": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "ended": {
            "type": [
              "string",
              "null"
            ]
          },
          "exit_code": {
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/SessionKind"
          },
          "last_output": {
            "type": [
              "string",
              "null"
            ]
          },
          "lost": {
            "description": "It ended with rookeryd or the host, not by itself.",
            "type": "boolean"
          },
          "output_size": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "rows": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "started": {
            "type": "string"
          },
          "started_by": {
            "$ref": "#/components/schemas/From"
          },
          "steps": {
            "items": {
              "$ref": "#/components/schemas/Step"
            },
            "type": "array"
          },
          "title": {
            "type": "string"
          },
          "user": {
            "type": "string"
          },
          "viewers": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "id",
          "kind",
          "title",
          "command",
          "user",
          "started_by",
          "started"
        ],
        "type": "object"
      },
      "SessionKind": {
        "enum": [
          "process",
          "terminal"
        ],
        "type": "string"
      },
      "Setting": {
        "properties": {
          "key": {
            "type": "string"
          },
          "meaning": {
            "type": "string"
          },
          "open": {
            "description": "Whether `settings.set` takes it.",
            "type": "boolean"
          },
          "value": {
            "description": "Empty when it is not set, and for a token.",
            "type": "string"
          }
        },
        "required": [
          "key",
          "value",
          "meaning",
          "open"
        ],
        "type": "object"
      },
      "SettingValue": {
        "properties": {
          "value": {
            "description": "Empty to go back to the default.",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "SetupClaim": {
        "description": "The server's token, collected with a setup key.",
        "properties": {
          "api": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "expires": {
            "type": "string"
          },
          "token": {
            "description": "The token of rookery serve, as in its serve.token.",
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "token",
          "version",
          "api",
          "expires"
        ],
        "type": "object"
      },
      "SetupKey": {
        "description": "What a setup key says of the server it is for.",
        "properties": {
          "api": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "expires": {
            "description": "When the key stops working, in RFC 3339.",
            "type": "string"
          },
          "version": {
            "description": "The version of rookery serve.",
            "type": "string"
          }
        },
        "required": [
          "version",
          "api",
          "expires"
        ],
        "type": "object"
      },
      "Signal": {
        "properties": {
          "signal": {
            "description": "`INT`, `TERM`, `HUP` or `KILL`.",
            "type": "string"
          }
        },
        "required": [
          "signal"
        ],
        "type": "object"
      },
      "StartSession": {
        "properties": {
          "cols": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "command": {
            "$ref": "#/components/schemas/CommandLine"
          },
          "cwd": {
            "type": [
              "string",
              "null"
            ]
          },
          "env": {
            "additionalProperties": {
              "type": "string"
            },
            "propertyNames": {
              "type": "string"
            },
            "type": "object"
          },
          "input": {
            "description": "Text for standard input; a process then sees the end of its input.",
            "type": [
              "string",
              "null"
            ]
          },
          "input_b64": {
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "$ref": "#/components/schemas/SessionKind"
          },
          "rows": {
            "format": "int32",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "timeout": {
            "description": "Seconds after which the command is ended.",
            "format": "int64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "user": {
            "description": "`agent`, `operator` (the SSH user) or `root`.",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "command"
        ],
        "type": "object"
      },
      "Started": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Session"
          },
          {
            "properties": {
              "output_b64": {
                "description": "A terminal's bytes.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "stderr_b64": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "stdout_b64": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "truncated": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        ],
        "description": "The answer to a start with `wait=`: the session and, when it has ended in\ntime, what it wrote."
      },
      "Stats": {
        "properties": {
          "cores": {
            "items": {
              "format": "double",
              "type": "number"
            },
            "type": "array"
          },
          "cpu": {
            "description": "Percent busy over 200 ms, all cores together.",
            "format": "double",
            "type": "number"
          },
          "filesystems": {
            "items": {
              "$ref": "#/components/schemas/Filesystem"
            },
            "type": "array"
          },
          "gpus": {
            "items": {
              "$ref": "#/components/schemas/Gpu"
            },
            "type": "array"
          },
          "hostname": {
            "type": "string"
          },
          "load": {
            "items": {
              "format": "double",
              "type": "number"
            },
            "type": "array"
          },
          "memory": {
            "$ref": "#/components/schemas/Memory"
          },
          "network": {
            "items": {
              "$ref": "#/components/schemas/Interface"
            },
            "type": "array"
          },
          "reboot_required": {
            "type": "boolean"
          },
          "sessions_running": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "swap": {
            "$ref": "#/components/schemas/Memory"
          },
          "units": {
            "items": {
              "$ref": "#/components/schemas/UnitState"
            },
            "type": "array"
          },
          "uptime": {
            "description": "Seconds.",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "hostname",
          "load",
          "cpu",
          "cores",
          "memory",
          "swap",
          "filesystems",
          "network",
          "uptime",
          "reboot_required",
          "units",
          "sessions_running"
        ],
        "type": "object"
      },
      "Step": {
        "properties": {
          "exit_code": {
            "format": "int32",
            "type": [
              "integer",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "user": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "user"
        ],
        "type": "object"
      },
      "TailnetDevice": {
        "description": "A host's device on the tailnet, from `tailscale status --json`. It\nholds public values only, which the control server's API finds it by.",
        "properties": {
          "addresses": {
            "description": "Its addresses on the tailnet.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "dns_name": {
            "description": "Its MagicDNS name, such as `studio.example.ts.net`, without the final dot.",
            "type": "string"
          },
          "host_name": {
            "description": "The machine's own hostname, as the client reports it.",
            "type": "string"
          },
          "id": {
            "description": "The device's stable id: Tailscale's `nodeId`, or the number of\nHeadscale's node.",
            "type": "string"
          },
          "tailnet": {
            "description": "The tailnet's name, when the client knows it.",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      },
      "Topic": {
        "description": "An entry of `/etc/rookery/channels.json`.",
        "properties": {
          "days": {
            "format": "int64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "keep": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Keep"
              },
              {
                "type": "null"
              }
            ]
          },
          "max": {
            "format": "int64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "topic": {
            "type": "string"
          }
        },
        "required": [
          "topic"
        ],
        "type": "object"
      },
      "Unit": {
        "properties": {
          "active": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "load": {
            "type": "string"
          },
          "sub": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "unit",
          "load",
          "active",
          "sub",
          "description"
        ],
        "type": "object"
      },
      "UnitState": {
        "properties": {
          "active": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "unit",
          "active"
        ],
        "type": "object"
      },
      "Version": {
        "properties": {
          "api": {
            "format": "int32",
            "minimum": 0,
            "type": "integer"
          },
          "applied": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/Applied",
                "description": "What the host's configuration was last applied from, when rookery\nrecorded it."
              },
              {
                "type": "null"
              }
            ]
          },
          "mode": {
            "description": "`system` or `single`.",
            "type": "string"
          },
          "simulated": {
            "description": "Whether it is simulated, as `rookery serve --simulate` and its hosts\nare: nothing it does reaches a real machine.",
            "type": "boolean"
          },
          "type": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/HostType",
                "description": "What was installed on the host, by that record: `managed` when\nonly the controller was, `workstation` for a whole profile. Absent\nwhen the host keeps no record."
              },
              {
                "type": "null"
              }
            ]
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "version",
          "api"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "description": "One API over all hosts, with the inbox and a key-value store. Everything under /v1/hosts/{name}/controller/ is that host's own API, passed through unchanged; only the controller's own `secrets` action is refused, which the server's `secrets` action of the host stands in for, and `endpoints.connect`, which the server opens itself for `resources.connect`. What can be done to a host or to the installation is listed at /v1/hosts/{name}/actions and /v1/installation/actions, and run by POST to an action's name there. Over TCP every request carries the server's token or an OAuth 2.0 access token as a bearer, and needs the role its operation names. The routes of the setup key take that key as the bearer instead.",
    "title": "rookery serve",
    "version": "0.6.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/access": {
      "get": {
        "operationId": "access",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccessInfo"
                }
              }
            },
            "description": "The caller's role"
          }
        },
        "summary": "What the caller may do here.",
        "tags": [
          "serve"
        ]
      }
    },
    "/v1/events": {
      "get": {
        "operationId": "stream_events",
        "parameters": [],
        "responses": {
          "101": {
            "description": "A WebSocket; its frames are in the AsyncAPI document"
          }
        },
        "summary": "Channel messages of chosen hosts, jobs, key-value changes and changes to hosts and resources together. The first frame sent names what to follow; each frame received says where it came from.",
        "tags": [
          "streams"
        ]
      }
    },
    "/v1/hosts": {
      "get": {
        "operationId": "hosts",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/HostInfo"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The saved hosts and whether each answers"
          }
        },
        "summary": "The saved hosts and whether each answers.",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{name}": {
      "delete": {
        "operationId": "remove_host",
        "parameters": [
          {
            "description": "A saved host, by its name or its id (bare or as `host_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Removed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It has a machine rookery created, which is deleted first, or one is being created"
          }
        },
        "summary": "Remove a host's profile. The host itself is left as it is.",
        "tags": [
          "set-up"
        ]
      },
      "get": {
        "operationId": "host",
        "parameters": [
          {
            "description": "A saved host, by its name or its id (bare or as `host_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HostInfo"
                }
              }
            },
            "description": "One host"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host"
          }
        },
        "summary": "One host: its address, and whether it answers.",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{name}/actions": {
      "get": {
        "operationId": "host_actions",
        "parameters": [
          {
            "description": "A saved host, by its name or its id (bare or as `host_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Action"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The actions, each saying whether it can run now"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host"
          }
        },
        "summary": "What can be done to a host: the actions its controller lists, and rookery's own.",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{name}/actions/{action}": {
      "post": {
        "operationId": "host_act",
        "parameters": [
          {
            "description": "A saved host, by its name or its id (bare or as `host_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The action, as hosts.actions names it",
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Act"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "description": "Its arguments, and a token that makes asking again safe"
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Answered at once: the result, or the terminal session to attach to"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Started as a job; an action of its controller also says its session"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An argument is missing, or the body is not one"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The caller's role is below the action's"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host or action"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Something else is being done to the host"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It cannot run on this host now; the message says why"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The host could not be reached"
          }
        },
        "summary": "Run one of a host's actions. One of rookery's that changes something is a job; an action of the host's controller is a session there, which a job follows unless it needs a terminal.",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/hosts/{name}/controller/actions": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_actions",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/HostAction"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The actions the caller may run, in the order of the file.",
        "tags": [
          "host: actions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/actions/{action}": {
      "post": {
        "description": "Host and agent level.",
        "operationId": "host_post_v1_actions__action_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A duration such as 30s, at most 10m: answer when the command has ended, with what it wrote.",
            "in": "query",
            "name": "wait",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunAction"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Started"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Run an action. It and what extends it are the steps of one session.",
        "tags": [
          "host: actions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/actions/{action}/choices/{argument}": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_actions__action__choices__argument_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "argument",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Choices"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The values to offer for an argument.",
        "tags": [
          "host: actions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/applied/profile": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_applied_profile",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeptProfile"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The profile the host keeps of itself, as the last apply or the first boot wrote it.",
        "tags": [
          "host: applied"
        ]
      }
    },
    "/v1/hosts/{name}/controller/channel": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_channel",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only topics starting with this.",
            "in": "query",
            "name": "topic",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Messages after this id; default 0.",
            "in": "query",
            "name": "since",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Most messages; default 100, at most 1000.",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "With a WebSocket handshake: the stream `channel` of the AsyncAPI document."
          },
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Messages"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Kept messages after `since`.",
        "tags": [
          "host: channel"
        ]
      }
    },
    "/v1/hosts/{name}/controller/channel/{topic}": {
      "post": {
        "description": "Host and agent level.",
        "operationId": "host_post_v1_channel___topic_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "topic",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Publish"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Publish a message on a topic.",
        "tags": [
          "host: channel"
        ]
      }
    },
    "/v1/hosts/{name}/controller/files": {
      "delete": {
        "description": "Host level only.",
        "operationId": "host_delete_v1_files",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "An absolute path under a root.",
            "in": "query",
            "name": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true for a folder with its contents.",
            "in": "query",
            "name": "recursive",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Remove a file or an empty folder; never a root itself.",
        "tags": [
          "host: files"
        ]
      },
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_files",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "An absolute path under a root.",
            "in": "query",
            "name": "path",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/octet-stream": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "A folder's entries (a Listing), or a file's content; Range is honoured. As the agent, under the configured roots.",
        "tags": [
          "host: files"
        ]
      },
      "put": {
        "description": "Host level only.",
        "operationId": "host_put_v1_files",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "An absolute path under a root.",
            "in": "query",
            "name": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true to replace an existing file.",
            "in": "query",
            "name": "overwrite",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Write one file, creating its folders.",
        "tags": [
          "host: files"
        ]
      }
    },
    "/v1/hosts/{name}/controller/logs": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_logs",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only this unit.",
            "in": "query",
            "name": "unit",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A cursor from an earlier entry, or a time.",
            "in": "query",
            "name": "since",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Most entries; default 100.",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "With a WebSocket handshake: the stream `logs` of the AsyncAPI document."
          },
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/LogEntry"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Journal entries.",
        "tags": [
          "host: logs"
        ]
      }
    },
    "/v1/hosts/{name}/controller/ports/{port}": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_ports__port_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "port",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "With a WebSocket handshake: the stream `port` of the AsyncAPI document."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Only as a WebSocket: a TCP connection to a port on the host's loopback. A port that nothing listens on is an error before the handshake.",
        "tags": [
          "host: ports"
        ]
      }
    },
    "/v1/hosts/{name}/controller/power/{verb}": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_power__verb_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "verb",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true to do it although sessions run.",
            "in": "query",
            "name": "force",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Reboot the host or power it off. Refused while sessions run.",
        "tags": [
          "host: power"
        ]
      }
    },
    "/v1/hosts/{name}/controller/processes": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_processes",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Process"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The processes, from /proc.",
        "tags": [
          "host: processes"
        ]
      }
    },
    "/v1/hosts/{name}/controller/processes/{pid}/signal": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_processes__pid__signal",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "pid",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Signal"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Send a signal to a process.",
        "tags": [
          "host: processes"
        ]
      }
    },
    "/v1/hosts/{name}/controller/reload": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_reload",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Read the configuration files again. Sessions go on.",
        "tags": [
          "host: reload"
        ]
      }
    },
    "/v1/hosts/{name}/controller/screenshot": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_screenshot",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The shared desktop as PNG.",
        "tags": [
          "host: screenshot"
        ]
      }
    },
    "/v1/hosts/{name}/controller/services": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_services",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Service"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The services that can be called, and whether each is up.",
        "tags": [
          "host: services"
        ]
      }
    },
    "/v1/hosts/{name}/controller/services/{plugin}/{name}/serve": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_services__plugin___name__serve",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "plugin",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "With a WebSocket handshake: the stream `serve` of the AsyncAPI document."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Only as a WebSocket: for the program that answers the service's calls.",
        "tags": [
          "host: services"
        ]
      }
    },
    "/v1/hosts/{name}/controller/services/{plugin}/{name}/{method}": {
      "post": {
        "description": "Host and agent level.",
        "operationId": "host_post_v1_services__plugin___name___method_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "plugin",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "method",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {}
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Call a method of the service PLUGIN/NAME: JSON in, JSON out.",
        "tags": [
          "host: services"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_sessions",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Session"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "All sessions, running and ended.",
        "tags": [
          "host: sessions"
        ]
      },
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_sessions",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A duration such as 30s, at most 10m: answer when the command has ended, with what it wrote.",
            "in": "query",
            "name": "wait",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StartSession"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Started"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Start a session.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions/{id}": {
      "delete": {
        "description": "Host level only.",
        "operationId": "host_delete_v1_sessions__id_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "End it if it runs (HUP, after five seconds KILL) and forget it with its transcript.",
        "tags": [
          "host: sessions"
        ]
      },
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_sessions__id_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "With a WebSocket handshake: the stream `session` of the AsyncAPI document."
          },
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Session"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "One session's state. The agent sees those it started through an action.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions/{id}/input": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_sessions__id__input",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Input"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Write to standard input or type into the terminal. Never recorded.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions/{id}/output": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_sessions__id__output",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "stdout, stderr or merged (default), for a process.",
            "in": "query",
            "name": "stream",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Byte offset to read from.",
            "in": "query",
            "name": "since",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Most bytes to return; default 1 MB.",
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Read lines from this line number (a process only).",
            "in": "query",
            "name": "line",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "How many lines; default 100.",
            "in": "query",
            "name": "count",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The last so many lines.",
            "in": "query",
            "name": "tail",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Output"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The transcript, by bytes or by lines.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions/{id}/resize": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_sessions__id__resize",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Resize"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Give a terminal a new size.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions/{id}/screen": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_sessions__id__screen",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "text (default) or ansi, which keeps colours.",
            "in": "query",
            "name": "format",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "That many lines of screen and scrollback instead.",
            "in": "query",
            "name": "tail",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Screen"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "A terminal as it looks now, as text.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/sessions/{id}/signal": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_sessions__id__signal",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Signal"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Send INT, TERM, HUP or KILL to the session's process group.",
        "tags": [
          "host: sessions"
        ]
      }
    },
    "/v1/hosts/{name}/controller/stats": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_stats",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Stats"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Load, CPU, memory, filesystems, network, GPU and unit states, read now.",
        "tags": [
          "host: stats"
        ]
      }
    },
    "/v1/hosts/{name}/controller/units": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_units",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Unit"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The units and their state.",
        "tags": [
          "host: units"
        ]
      }
    },
    "/v1/hosts/{name}/controller/units/{unit}": {
      "get": {
        "description": "Host level only.",
        "operationId": "host_get_v1_units__unit_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "unit",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "type": "object"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "One unit's properties, as systemctl show gives them.",
        "tags": [
          "host: units"
        ]
      }
    },
    "/v1/hosts/{name}/controller/units/{unit}/{verb}": {
      "post": {
        "description": "Host level only.",
        "operationId": "host_post_v1_units__unit___verb_",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "unit",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "verb",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "Start, stop, restart, reload, enable or disable a unit.",
        "tags": [
          "host: units"
        ]
      }
    },
    "/v1/hosts/{name}/controller/version": {
      "get": {
        "description": "Host and agent level.",
        "operationId": "host_get_v1_version",
        "parameters": [
          {
            "description": "A saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "Done."
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An error."
          }
        },
        "summary": "The version of rookeryd and of its API.",
        "tags": [
          "host: version"
        ]
      }
    },
    "/v1/hosts/{name}/credentials": {
      "get": {
        "operationId": "credentials",
        "parameters": [
          {
            "description": "A saved host, by its name or its id (bare or as `host_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Credentials"
                }
              }
            },
            "description": "The passwords by account; none when none were generated"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host"
          }
        },
        "summary": "The passwords the server generated for a host's accounts.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/hosts/{name}/profile": {
      "get": {
        "operationId": "profile",
        "parameters": [
          {
            "description": "A saved host, by its name or its id (bare or as `host_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "The profile, with the passwords and keys in it"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host"
          }
        },
        "summary": "A host's profile, as it is saved.",
        "tags": [
          "set-up"
        ]
      },
      "put": {
        "operationId": "save_profile",
        "parameters": [
          {
            "description": "The name to save it under: letters, digits, `-`, `_` and `.`, and not in the shape of an id; or the id of a saved host",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {}
            }
          },
          "description": "The whole profile. A workstation's has a builder object; a host of the type ssh or managed needs only type and access",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Saved"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a profile, or not a name"
          }
        },
        "summary": "Save a host's profile: a new host, or a changed one. A host that is not a workstation needs only its type and access.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/inbox": {
      "get": {
        "operationId": "inbox",
        "parameters": [
          {
            "description": "Only this host.",
            "in": "query",
            "name": "host",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only topics starting with this.",
            "in": "query",
            "name": "topic",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only messages taken in before this `seq`.",
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "Only done ones, or only those that are not.",
            "in": "query",
            "name": "done",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "At most this many (default 100, at most 1,000).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "As a WebSocket: messages as they are taken in"
          },
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Inbox"
                }
              }
            },
            "description": "Stored messages, newest first"
          }
        },
        "summary": "Messages taken in from the hosts' channels.",
        "tags": [
          "inbox"
        ]
      }
    },
    "/v1/inbox/{host}/{id}/done": {
      "delete": {
        "operationId": "mark_open",
        "parameters": [
          {
            "description": "The host it came from, by its name or its id",
            "in": "path",
            "name": "host",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The message's id on that host",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "No longer marked done"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such message"
          }
        },
        "summary": "Mark a message as open again.",
        "tags": [
          "inbox"
        ]
      },
      "post": {
        "operationId": "mark_done",
        "parameters": [
          {
            "description": "The host it came from, by its name or its id",
            "in": "path",
            "name": "host",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The message's id on that host",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Marked done"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such message"
          }
        },
        "summary": "Mark a message as done.",
        "tags": [
          "inbox"
        ]
      }
    },
    "/v1/installation/actions": {
      "get": {
        "operationId": "list",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Action"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The actions"
          }
        },
        "summary": "What can be done to the installation as a whole, such as a roll-out over its hosts.",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/installation/actions/{action}": {
      "post": {
        "operationId": "act",
        "parameters": [
          {
            "description": "The action, as installation.actions names it",
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Act"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "description": "Its arguments, and a token that makes asking again safe"
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Started as a job"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An argument is wrong, or the body is not one"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The caller's role is below the action's"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such action, or a host it names"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Another one is running"
          }
        },
        "summary": "Run one of the installation's actions, as a job.",
        "tags": [
          "hosts"
        ]
      }
    },
    "/v1/jobs": {
      "get": {
        "operationId": "jobs",
        "parameters": [
          {
            "description": "Only the jobs of this subject: `host:HOST`, `provisioner:PROVISIONER`, `resource:ID` or `installation`, each by name or id.",
            "in": "query",
            "name": "subject",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only the jobs about this host, by name or id, alone or among others, as a roll-out is.",
            "in": "query",
            "name": "host",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only the jobs that have not ended, or with `false` only those that have.",
            "in": "query",
            "name": "running",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Only the jobs that started before the job of this id: the next page after it.",
            "in": "query",
            "name": "before",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "At most this many (default 100, at most 1,000).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/JobInfo"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Jobs, newest first"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "`before` names no job"
          }
        },
        "summary": "The jobs, newest first.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/{id}": {
      "get": {
        "operationId": "job",
        "parameters": [
          {
            "description": "A job's id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "As a WebSocket: its output as it is produced"
          },
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobInfo"
                }
              }
            },
            "description": "One job"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such job"
          }
        },
        "summary": "One job's state.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/{id}/output": {
      "get": {
        "operationId": "job_output",
        "parameters": [
          {
            "description": "A job's id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "By bytes: start at this offset.",
            "in": "query",
            "name": "since",
            "required": false,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "By bytes: at most this many (default and most 1 MB).",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "By lines: start at this line, from 0.",
            "in": "query",
            "name": "line",
            "required": false,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "By lines: this many (default 100).",
            "in": "query",
            "name": "count",
            "required": false,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          },
          {
            "description": "The last lines.",
            "in": "query",
            "name": "tail",
            "required": false,
            "schema": {
              "format": "int64",
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Output"
                }
              }
            },
            "description": "A piece of the job's output, by bytes or by lines"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such job, or its output is not on this machine, as for a job of an installation restored from its store"
          }
        },
        "summary": "What a job wrote, by bytes or by lines.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/jobs/{id}/stop": {
      "post": {
        "operationId": "stop_job",
        "parameters": [
          {
            "description": "A job's id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobInfo"
                }
              }
            },
            "description": "Asked to stop; it ends soon, as following it shows"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The caller may not start a job of its kind, so may not stop it"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such job"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It has ended already"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It runs in another rookery serve of the same store"
          }
        },
        "summary": "Stop a running job: its programs end, a session it follows ends on its host, and its record says who stopped it.",
        "tags": [
          "jobs"
        ]
      }
    },
    "/v1/keys": {
      "get": {
        "operationId": "list",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyList"
                }
              }
            },
            "description": "The keys; the key rookery is first"
          }
        },
        "summary": "The SSH keys of the server's key ring, by their public halves, with the hosts that log in with each and the key that replaces it while it rotates.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/keys/{name}": {
      "delete": {
        "operationId": "remove",
        "parameters": [
          {
            "description": "The key, by its name or its id (bare or as `key_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Removed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such key"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It is rookery's, in use or rotating"
          }
        },
        "summary": "Remove a key from the ring. Refused for the key rookery, while a host logs in with the key, and while it rotates.",
        "tags": [
          "set-up"
        ]
      },
      "put": {
        "operationId": "add",
        "parameters": [
          {
            "description": "The key's name: letters, digits, - and _, and not in the shape of an id",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/octet-stream": {
              "schema": {
                "items": {
                  "format": "int32",
                  "minimum": 0,
                  "type": "integer"
                },
                "type": "array"
              }
            }
          },
          "description": "An OpenSSH private key, or nothing",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyInfo"
                }
              }
            },
            "description": "Added"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a name, not a private key, or a key with a passphrase"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "There is a key of that name"
          }
        },
        "summary": "Add a key to the ring: a new ed25519 key without a body, or the OpenSSH private key in the body, which may have no passphrase. The answer has its public half only.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/keys/{name}/rotate": {
      "post": {
        "operationId": "rotate",
        "parameters": [
          {
            "description": "The key, by its name or its id (bare or as `key_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "The job"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such key"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "A rotation runs already"
          }
        },
        "summary": "Replace a key on every host that takes it, as a job: a new key beside it, and on each host the new one added, a login with it checked, and the old one removed. A host that does not answer stays pending; running it again goes on from there. When none is pending the old key is deleted.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/kv/{namespace}": {
      "get": {
        "operationId": "kv_list",
        "parameters": [
          {
            "description": "A namespace",
            "in": "path",
            "name": "namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "As a WebSocket: changes to the namespace"
          },
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KvList"
                }
              }
            },
            "description": "The namespace's keys with their values"
          }
        },
        "summary": "The keys of a namespace with their values.",
        "tags": [
          "kv"
        ]
      }
    },
    "/v1/kv/{namespace}/{key}": {
      "delete": {
        "operationId": "kv_delete",
        "parameters": [
          {
            "description": "A namespace",
            "in": "path",
            "name": "namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A key",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Remove only if the key is at this revision",
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Removed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such key"
          },
          "412": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Someone else wrote in between"
          }
        },
        "summary": "Remove a key.",
        "tags": [
          "kv"
        ]
      },
      "get": {
        "operationId": "kv_get",
        "parameters": [
          {
            "description": "A namespace",
            "in": "path",
            "name": "namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A key",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KvEntry"
                }
              }
            },
            "description": "The value and its revision, which is also the ETag"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such key"
          }
        },
        "summary": "One key's value and revision.",
        "tags": [
          "kv"
        ]
      },
      "put": {
        "operationId": "kv_put",
        "parameters": [
          {
            "description": "A namespace",
            "in": "path",
            "name": "namespace",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A key",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Write only if the key is at this revision",
            "in": "header",
            "name": "If-Match",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          {
            "description": "`*`: write only if the key is new",
            "in": "header",
            "name": "If-None-Match",
            "required": false,
            "schema": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {}
            }
          },
          "description": "The value: any JSON, at most 64 KB",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KvWritten"
                }
              }
            },
            "description": "Written"
          },
          "412": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Someone else wrote in between"
          },
          "413": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The value is too large"
          }
        },
        "summary": "Write a key, optionally only if nobody wrote in between.",
        "tags": [
          "kv"
        ]
      }
    },
    "/v1/plugins": {
      "get": {
        "operationId": "plugins",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginList"
                }
              }
            },
            "description": "The plugins with their features"
          }
        },
        "summary": "The plugins: those that come with rookery and the server's own.",
        "tags": [
          "set-up"
        ]
      },
      "post": {
        "operationId": "add_plugin",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PluginSpec"
              }
            }
          },
          "description": "What to install",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginReport"
                }
              }
            },
            "description": "Installed; what npm said"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a package or address, or npm failed; the message has its output"
          }
        },
        "summary": "Install a plugin with npm from a registry or an address.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/plugins/package": {
      "post": {
        "operationId": "upload_plugin",
        "requestBody": {
          "content": {
            "application/gzip": {
              "schema": {
                "items": {
                  "format": "int32",
                  "minimum": 0,
                  "type": "integer"
                },
                "type": "array"
              }
            }
          },
          "description": "The .tgz",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginReport"
                }
              }
            },
            "description": "Installed; what npm said"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a .tgz, or npm failed; the message has its output"
          }
        },
        "summary": "Install a plugin from a .tgz, as npm pack makes one, which the server keeps.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/plugins/update": {
      "post": {
        "operationId": "update_plugins",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/PluginUpdateSpec"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "description": "The plugin, by id or npm name; all without one"
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginReport"
                }
              }
            },
            "description": "Updated; what npm said, and the hosts that need applying"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It has no registry to ask, comes with rookery, or npm failed; the message says which"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such plugin"
          }
        },
        "summary": "Update one of the server's own plugins, or all, to the latest version of their registry, and say which hosts are behind then.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/plugins/updates": {
      "get": {
        "operationId": "check_plugins",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginUpdates"
                }
              }
            },
            "description": "Each of the server's own plugins, with the latest version where there is a newer one"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "npm could not be run"
          }
        },
        "summary": "Ask the registries the server's own plugins came from whether they have newer versions.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/plugins/{id}": {
      "delete": {
        "operationId": "remove_plugin",
        "parameters": [
          {
            "description": "The plugin's id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PluginReport"
                }
              }
            },
            "description": "Removed; what npm said"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such plugin"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It comes with rookery and stays"
          }
        },
        "summary": "Remove one of the server's own plugins.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/provisioner-types": {
      "get": {
        "operationId": "types",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ProvisionerInfo"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Each type as `PLUGIN/ID` in `id` and `type`, with what it asks for and can make"
          }
        },
        "summary": "The types of provisioner the plugins bring, which a provisioner is registered as.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/provisioners": {
      "get": {
        "operationId": "list",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ProvisionerInfo"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The provisioners, each with its settings, the required secrets that have no value, and as `problem` why it cannot be used"
          }
        },
        "summary": "What the plugins can create machines and other resources with, what each asks for and can do, and whether it can be used here.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/provisioners/{name}": {
      "delete": {
        "operationId": "remove",
        "parameters": [
          {
            "description": "Its name or its id (bare or as `prov_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Forgotten"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such provisioner"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It still holds resources; the message names them"
          }
        },
        "summary": "Forget a registered provisioner, with its settings and the secrets it keeps of its own. It is kept while it holds resources.",
        "tags": [
          "set-up"
        ]
      },
      "get": {
        "operationId": "provisioner",
        "parameters": [
          {
            "description": "The provisioner, by its name or its id (bare or as `prov_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Values of the provisioner's own arguments as `NAME=VALUE` for this once, such as another server to ask; the others are its settings",
            "explode": true,
            "in": "query",
            "name": "arguments",
            "required": false,
            "schema": {
              "additionalProperties": {
                "type": "string"
              },
              "propertyNames": {
                "type": "string"
              },
              "type": "object"
            },
            "style": "form"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvisionerState"
                }
              }
            },
            "description": "What it said. A state of `unreachable` or `unusable` comes with why as its message"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such provisioner"
          }
        },
        "summary": "A provisioner's page: what it says of itself now, such as whether its engine answers, and what it holds: rookery's resources, with what its own list says.",
        "tags": [
          "set-up"
        ]
      },
      "put": {
        "operationId": "save",
        "parameters": [
          {
            "description": "Its name: lowercase letters, digits, - and _, starting with a letter, and not in the shape of an id; or the id of a registered one",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SavedProvisioner"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProvisionerInfo"
                }
              }
            },
            "description": "Registered, as it is listed"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The name, the type or a setting does not fit; the message says which"
          }
        },
        "summary": "Register a provisioner under a name of its own, of a type a plugin brings, or change the settings of one that is registered. A registered one keeps its type.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/provisioners/{name}/actions": {
      "get": {
        "operationId": "provisioner_actions",
        "parameters": [
          {
            "description": "The provisioner, by its name or its id (bare or as `prov_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Action"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The actions, each saying whether it can run here now"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such provisioner"
          }
        },
        "summary": "What can be done to a provisioner: its plugin's actions, and rookery's own settings of it.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/provisioners/{name}/actions/{action}": {
      "post": {
        "operationId": "provisioner_act",
        "parameters": [
          {
            "description": "The provisioner, by its name or its id (bare or as `prov_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The action, as provisioners.actions names it",
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Act"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "description": "Its arguments, which may also give the provisioner's own for this once, and a token that makes asking again safe"
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Answered at once: its `message` and `details` as the result"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Started as a job"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An argument is missing or unknown, or the body is not one"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The caller's role is below the action's"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such provisioner or action"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Something else is being done to the provisioner"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It cannot run here now; the message says why"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The provisioner failed, as when its engine does not answer"
          }
        },
        "summary": "Run one of a provisioner's actions. One that changes something is a job, which holds the provisioner's lock; one that only reads answers at once.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/registries": {
      "get": {
        "operationId": "registries",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Registries"
                }
              }
            },
            "description": "The registries by name"
          }
        },
        "summary": "The registries.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/registries/{name}": {
      "delete": {
        "operationId": "remove_registry",
        "parameters": [
          {
            "description": "A registry, by its name or its id (bare or as `reg_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Removed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such registry"
          }
        },
        "summary": "Remove a registry with its stored login.",
        "tags": [
          "set-up"
        ]
      },
      "put": {
        "operationId": "save_registry",
        "parameters": [
          {
            "description": "The registry's name here, or the id of one there is",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {}
            }
          },
          "description": "`type`, `url`, and optionally `username` and `repositories`",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Saved"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a registry"
          }
        },
        "summary": "Add a registry, or change one.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/registries/{name}/check": {
      "post": {
        "operationId": "check_registry",
        "parameters": [
          {
            "description": "A registry, by its name or its id (bare or as `reg_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Checked"
                }
              }
            },
            "description": "What was found"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such registry"
          }
        },
        "summary": "Whether a registry answers and takes its login.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/registries/{name}/rename": {
      "post": {
        "operationId": "rename_registry",
        "parameters": [
          {
            "description": "The registry, by its name or its id (bare or as `reg_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Rename"
              }
            }
          },
          "description": "The new name",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Renamed, with its login: the hosts that use it refer to it still"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a name for a registry"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such registry"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The name is taken"
          }
        },
        "summary": "Give a registry another name.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/resources": {
      "get": {
        "operationId": "list",
        "parameters": [
          {
            "description": "Only those of this provisioner, by its name.",
            "in": "query",
            "name": "provisioner",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only those of this kind, such as `machine` or `deployment`.",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only the machine of this saved host.",
            "in": "query",
            "name": "host",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Resource"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The resources, each as it was last seen"
          }
        },
        "summary": "What provisioners made for rookery, as rookery's records have it. Nothing is asked of the provisioners.",
        "tags": [
          "resources"
        ]
      },
      "post": {
        "operationId": "create",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NewResource"
              }
            }
          },
          "description": "The provisioner, the kind, its name or host, arguments, the specification and the secrets it is given, and a token that makes asking again safe",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Created"
                }
              }
            },
            "description": "Its record, saved before anything is made, and the job that makes it"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An argument, a secret or the specification is missing or does not fit; the message says which"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such host or provisioner"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "One of that name exists already, or something else is being done to it"
          }
        },
        "summary": "Create a resource with a provisioner, as a job: a host's machine, which is then set up as the host, or a kind its plugin declares, such as a deployment from a specification.",
        "tags": [
          "resources"
        ]
      }
    },
    "/v1/resources/{id}": {
      "delete": {
        "operationId": "remove",
        "parameters": [
          {
            "description": "rookery's id of the resource, bare or as `res_ID`",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Any text of the caller's; the same again answers with the first job.",
            "in": "query",
            "name": "token",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Started as a job"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such resource"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Something else is being done to it"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Its provisioner cannot be asked now; the message says why"
          }
        },
        "summary": "Remove a resource with its provisioner, as a job, and forget it. A host's profile stays.",
        "tags": [
          "resources"
        ]
      },
      "get": {
        "operationId": "get",
        "parameters": [
          {
            "description": "rookery's id of the resource, bare or as `res_ID`",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Resource"
                }
              }
            },
            "description": "The resource; a state of `unknown` comes with the problem"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such resource"
          }
        },
        "summary": "One resource, as its provisioner says it is now. One it no longer finds is `missing`, and its record stays.",
        "tags": [
          "resources"
        ]
      },
      "put": {
        "operationId": "change",
        "parameters": [
          {
            "description": "rookery's id of the resource, bare or as `res_ID`",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResourceChange"
              }
            }
          },
          "description": "What changes, and a token that makes asking again safe",
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Started as a job"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An argument, a secret or the specification does not fit"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such resource"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Something else is being done to it"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Its kind cannot be changed, or it is not made yet"
          }
        },
        "summary": "Change a resource, as a job: other values of its kind's arguments, a new specification, other secrets. What is not given stays.",
        "tags": [
          "resources"
        ]
      }
    },
    "/v1/resources/{id}/actions": {
      "get": {
        "operationId": "actions",
        "parameters": [
          {
            "description": "rookery's id of the resource, bare or as `res_ID`",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Action"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The actions, each saying whether it can run now"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such resource"
          }
        },
        "summary": "What can be done to a resource: start, stop and change as its kind can, its plugin's actions of the kind, and removing it.",
        "tags": [
          "resources"
        ]
      }
    },
    "/v1/resources/{id}/actions/{action}": {
      "post": {
        "operationId": "act",
        "parameters": [
          {
            "description": "rookery's id of the resource, bare or as `res_ID`",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The action, as resources.actions names it",
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/Act"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "description": "Its arguments, and a token that makes asking again safe"
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Answered at once: its `message` and `details` as the result"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acted"
                }
              }
            },
            "description": "Started as a job"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "An argument is missing or unknown, or the body is not one"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The caller's role is below the action's"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such resource or action"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Something else is being done to it"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It cannot run now; the message says why"
          },
          "502": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The provisioner failed"
          }
        },
        "summary": "Run one of a resource's actions. One that changes something is a job of the resource, which holds its lock; one that only reads answers at once.",
        "tags": [
          "resources"
        ]
      }
    },
    "/v1/resources/{id}/endpoints/{endpoint}": {
      "get": {
        "operationId": "stream_resource-connect",
        "parameters": [],
        "responses": {
          "101": {
            "description": "A WebSocket; its frames are in the AsyncAPI document"
          }
        },
        "summary": "A TCP connection to an endpoint its provisioner reported for a resource, named by the endpoint's name or its port. The server dials it first, so one that nothing answers on, or an address rookery refuses, is an error and not a stream.",
        "tags": [
          "streams"
        ]
      }
    },
    "/v1/resources/{id}/logs": {
      "get": {
        "operationId": "logs",
        "parameters": [
          {
            "description": "rookery's id of the resource, bare or as `res_ID`",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The last so many lines; all when 0 (default 100).",
            "in": "query",
            "name": "tail",
            "required": false,
            "schema": {
              "format": "int32",
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "101": {
            "description": "As a WebSocket: the lines as they come"
          },
          "200": {
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "The last lines"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Its kind gives no logs, or it is not made yet"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such resource"
          }
        },
        "summary": "What a resource wrote, as its provisioner gives it, with secrets masked: the last lines as text, or as a WebSocket those and what follows.",
        "tags": [
          "resources"
        ]
      }
    },
    "/v1/secrets": {
      "get": {
        "operationId": "secrets",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecretNames"
                }
              }
            },
            "description": "The names"
          }
        },
        "summary": "The names of the secrets.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/secrets/{name}": {
      "delete": {
        "operationId": "remove_secret",
        "parameters": [
          {
            "description": "The secret, by its name or its id (bare or as `sec_ID`), or the address of one that belongs to something",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Removed"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such secret"
          }
        },
        "summary": "Remove a secret.",
        "tags": [
          "set-up"
        ]
      },
      "put": {
        "operationId": "set_secret",
        "parameters": [
          {
            "description": "The secret, by its name or its id (bare or as `sec_ID`); `registry/REGISTRY` is a registry's login, `ssh/HOST` and `sudo/HOST` a host's passwords and `provisioner/PROVISIONER/SECRET` a provisioner's own",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SecretValue"
              }
            }
          },
          "description": "The value",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Kept"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a name"
          }
        },
        "summary": "Set a secret's value.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/secrets/{name}/rename": {
      "post": {
        "operationId": "rename_secret",
        "parameters": [
          {
            "description": "The secret, by its name or its id (bare or as `sec_ID`)",
            "in": "path",
            "name": "name",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Rename"
              }
            }
          },
          "description": "The new name",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Renamed: the profiles that hand it to hosts refer to it still"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "Not a name for a secret, or one that belongs to something"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "No such secret"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The name is taken"
          }
        },
        "summary": "Give a global secret another name.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/settings": {
      "get": {
        "operationId": "settings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Setting"
                  },
                  "type": "array"
                }
              }
            },
            "description": "The settings"
          }
        },
        "summary": "The server's settings.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/settings/{key}": {
      "put": {
        "operationId": "set_setting",
        "parameters": [
          {
            "description": "The setting",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SettingValue"
              }
            }
          },
          "description": "The value",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "Saved"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "This one is set on the server itself"
          }
        },
        "summary": "Change one of the settings that are open to callers, or any for the user the server runs as.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/setup": {
      "get": {
        "operationId": "catalogue",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalogue"
                }
              }
            },
            "description": "The starting profile and the plugins' features"
          }
        },
        "summary": "What a new host starts from, and what plugins can install on one.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/setup-key": {
      "delete": {
        "operationId": "done",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Done"
                }
              }
            },
            "description": "The key is deleted"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The key is wrong, missing or expired"
          }
        },
        "summary": "End the setup key, once its user has the token.",
        "tags": [
          "setup_key"
        ]
      },
      "get": {
        "operationId": "check",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SetupKey"
                }
              }
            },
            "description": "The server's version and when the key expires"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The key is wrong, missing or expired"
          }
        },
        "summary": "Whether a setup key works, and the rookery serve it is for.",
        "tags": [
          "setup_key"
        ]
      },
      "post": {
        "operationId": "claim",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SetupClaim"
                }
              }
            },
            "description": "The server's token"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "The key is wrong, missing or expired"
          },
          "501": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "This rookery serve takes no token over the network"
          }
        },
        "summary": "Collect the server's token with a setup key. It can be asked again until the key is done.",
        "tags": [
          "setup_key"
        ]
      }
    },
    "/v1/setup/generate": {
      "post": {
        "operationId": "generate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Generate"
              }
            }
          },
          "description": "What to make",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Generated"
                }
              }
            },
            "description": "What was made"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            },
            "description": "It could not be made; the message says why"
          }
        },
        "summary": "Make up a host name, or hash or make up a password.",
        "tags": [
          "set-up"
        ]
      }
    },
    "/v1/version": {
      "get": {
        "operationId": "version",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Version"
                }
              }
            },
            "description": "The version of rookery serve"
          }
        },
        "summary": "The version of rookery serve and of its API.",
        "tags": [
          "serve"
        ]
      }
    }
  }
}
