{
  "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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."
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      },
      "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"
      }
    }
  },
  "description": "The operations of rookery serve. Every operation of a host is one here too: on the portal with `\"host\": \"NAME\"` in the frame, over HTTP under /v1/hosts/NAME/controller. Only the controller's own `secrets` action is refused, for which the server's `secrets` action of the host sends the server's secrets, and `endpoints.connect`, which the server opens itself for `resources.connect`. An action's own role is asked when it runs. Each operation names the least role a caller over TCP needs: view, operate or admin.",
  "hosts": true,
  "operations": [
    {
      "args": [],
      "group": "general",
      "http": {
        "method": "GET",
        "path": "/v1/version"
      },
      "kind": "call",
      "name": "version",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Version"
        }
      },
      "role": "view",
      "summary": "The version of rookery serve and of its API."
    },
    {
      "args": [],
      "group": "general",
      "http": {
        "method": "GET",
        "path": "/v1/access"
      },
      "kind": "call",
      "name": "access",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/AccessInfo"
        }
      },
      "role": "view",
      "summary": "What the caller may do here."
    },
    {
      "args": [],
      "errors": [
        {
          "description": "The key is wrong, missing or expired",
          "status": "401"
        }
      ],
      "group": "setup_key",
      "http": {
        "method": "GET",
        "path": "/v1/setup-key"
      },
      "http_only": "it is for a caller that has no token yet",
      "key": "the setup key",
      "kind": "call",
      "name": "setup_key.check",
      "portal": false,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/SetupKey"
        }
      },
      "summary": "Whether a setup key works, and the rookery serve it is for."
    },
    {
      "args": [],
      "errors": [
        {
          "description": "The key is wrong, missing or expired",
          "status": "401"
        },
        {
          "description": "This rookery serve takes no token over the network",
          "status": "501"
        }
      ],
      "group": "setup_key",
      "http": {
        "method": "POST",
        "path": "/v1/setup-key"
      },
      "http_only": "it is for a caller that has no token yet",
      "key": "the setup key",
      "kind": "call",
      "name": "setup_key.claim",
      "portal": false,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/SetupClaim"
        }
      },
      "summary": "Collect the server's token with a setup key. It can be asked again until the key is done."
    },
    {
      "args": [],
      "errors": [
        {
          "description": "The key is wrong, missing or expired",
          "status": "401"
        }
      ],
      "group": "setup_key",
      "http": {
        "method": "DELETE",
        "path": "/v1/setup-key"
      },
      "http_only": "it is for a caller that has no token yet",
      "key": "the setup key",
      "kind": "call",
      "name": "setup_key.done",
      "portal": false,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "summary": "End the setup key, once its user has the token."
    },
    {
      "args": [],
      "group": "hosts",
      "http": {
        "method": "GET",
        "path": "/v1/hosts"
      },
      "kind": "call",
      "name": "hosts.list",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/HostInfo"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "The saved hosts and whether each answers."
    },
    {
      "args": [
        {
          "description": "A saved host, by its name or its id (bare or as `host_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such host",
          "status": "404"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "GET",
        "path": "/v1/hosts/{name}"
      },
      "kind": "call",
      "name": "hosts.get",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/HostInfo"
        }
      },
      "role": "view",
      "summary": "One host: its address, and whether it answers."
    },
    {
      "args": [
        {
          "description": "A saved host, by its name or its id (bare or as `host_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such host",
          "status": "404"
        },
        {
          "description": "It has a machine rookery created, which is deleted first, or one is being created",
          "status": "409"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "DELETE",
        "path": "/v1/hosts/{name}"
      },
      "kind": "call",
      "name": "hosts.remove",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Remove a host's profile. The host itself is left as it is."
    },
    {
      "args": [
        {
          "description": "A saved host, by its name or its id (bare or as `host_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such host",
          "status": "404"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "GET",
        "path": "/v1/hosts/{name}/profile"
      },
      "kind": "call",
      "name": "hosts.profile",
      "portal": true,
      "result": {
        "schema": {}
      },
      "role": "admin",
      "summary": "A host's profile, as it is saved."
    },
    {
      "args": [
        {
          "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
        }
      ],
      "data": {
        "description": "The whole profile. A workstation's has a builder object; a host of the type ssh or managed needs only type and access",
        "schema": {}
      },
      "errors": [
        {
          "description": "Not a profile, or not a name",
          "status": "400"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "PUT",
        "path": "/v1/hosts/{name}/profile"
      },
      "kind": "call",
      "name": "hosts.save",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "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."
    },
    {
      "args": [
        {
          "description": "A saved host, by its name or its id (bare or as `host_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such host",
          "status": "404"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "GET",
        "path": "/v1/hosts/{name}/credentials"
      },
      "kind": "call",
      "name": "hosts.credentials",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Credentials"
        }
      },
      "role": "admin",
      "summary": "The passwords the server generated for a host's accounts."
    },
    {
      "args": [
        {
          "description": "A saved host, by its name or its id (bare or as `host_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such host",
          "status": "404"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "GET",
        "path": "/v1/hosts/{name}/actions"
      },
      "kind": "call",
      "name": "hosts.actions",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/Action"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "What can be done to a host: the actions its controller lists, and rookery's own."
    },
    {
      "args": [
        {
          "description": "A saved host, by its name or its id (bare or as `host_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        },
        {
          "description": "The action, as hosts.actions names it",
          "in": "path",
          "name": "action",
          "required": true
        }
      ],
      "data": {
        "description": "Its arguments, and a token that makes asking again safe",
        "schema": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Act"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "errors": [
        {
          "description": "An argument is missing, or the body is not one",
          "status": "400"
        },
        {
          "description": "The caller's role is below the action's",
          "status": "403"
        },
        {
          "description": "No such host or action",
          "status": "404"
        },
        {
          "description": "Something else is being done to the host",
          "status": "409"
        },
        {
          "description": "It cannot run on this host now; the message says why",
          "status": "501"
        },
        {
          "description": "The host could not be reached",
          "status": "502"
        }
      ],
      "group": "hosts",
      "http": {
        "method": "POST",
        "path": "/v1/hosts/{name}/actions/{action}"
      },
      "kind": "call",
      "name": "hosts.act",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Acted"
        }
      },
      "role": "view",
      "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."
    },
    {
      "args": [],
      "group": "installation",
      "http": {
        "method": "GET",
        "path": "/v1/installation/actions"
      },
      "kind": "call",
      "name": "installation.actions",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/Action"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "What can be done to the installation as a whole, such as a roll-out over its hosts."
    },
    {
      "args": [
        {
          "description": "The action, as installation.actions names it",
          "in": "path",
          "name": "action",
          "required": true
        }
      ],
      "data": {
        "description": "Its arguments, and a token that makes asking again safe",
        "schema": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Act"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "errors": [
        {
          "description": "An argument is wrong, or the body is not one",
          "status": "400"
        },
        {
          "description": "The caller's role is below the action's",
          "status": "403"
        },
        {
          "description": "No such action, or a host it names",
          "status": "404"
        },
        {
          "description": "Another one is running",
          "status": "409"
        }
      ],
      "group": "installation",
      "http": {
        "method": "POST",
        "path": "/v1/installation/actions/{action}"
      },
      "kind": "call",
      "name": "installation.act",
      "portal": true,
      "result": null,
      "role": "view",
      "summary": "Run one of the installation's actions, as a job."
    },
    {
      "args": [],
      "group": "secrets",
      "http": {
        "method": "GET",
        "path": "/v1/secrets"
      },
      "kind": "call",
      "name": "secrets.list",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/SecretNames"
        }
      },
      "role": "admin",
      "summary": "The names of the secrets."
    },
    {
      "args": [
        {
          "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
        }
      ],
      "data": {
        "description": "The value",
        "schema": {
          "$ref": "#/components/schemas/SecretValue"
        }
      },
      "errors": [
        {
          "description": "Not a name",
          "status": "400"
        }
      ],
      "group": "secrets",
      "http": {
        "method": "PUT",
        "path": "/v1/secrets/{name}"
      },
      "kind": "call",
      "name": "secrets.set",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Set a secret's value."
    },
    {
      "args": [
        {
          "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
        }
      ],
      "errors": [
        {
          "description": "No such secret",
          "status": "404"
        }
      ],
      "group": "secrets",
      "http": {
        "method": "DELETE",
        "path": "/v1/secrets/{name}"
      },
      "kind": "call",
      "name": "secrets.remove",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Remove a secret."
    },
    {
      "args": [
        {
          "description": "The secret, by its name or its id (bare or as `sec_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "data": {
        "description": "The new name",
        "schema": {
          "$ref": "#/components/schemas/Rename"
        }
      },
      "errors": [
        {
          "description": "Not a name for a secret, or one that belongs to something",
          "status": "400"
        },
        {
          "description": "No such secret",
          "status": "404"
        },
        {
          "description": "The name is taken",
          "status": "409"
        }
      ],
      "group": "secrets",
      "http": {
        "method": "POST",
        "path": "/v1/secrets/{name}/rename"
      },
      "kind": "call",
      "name": "secrets.rename",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Give a global secret another name."
    },
    {
      "args": [],
      "group": "keys",
      "http": {
        "method": "GET",
        "path": "/v1/keys"
      },
      "kind": "call",
      "name": "keys.list",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/KeyList"
        }
      },
      "role": "admin",
      "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."
    },
    {
      "args": [
        {
          "description": "The key's name: letters, digits, - and _, and not in the shape of an id",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "data": {
        "bytes": true
      },
      "errors": [
        {
          "description": "Not a name, not a private key, or a key with a passphrase",
          "status": "400"
        },
        {
          "description": "There is a key of that name",
          "status": "409"
        }
      ],
      "group": "keys",
      "http": {
        "method": "PUT",
        "path": "/v1/keys/{name}"
      },
      "kind": "call",
      "name": "keys.add",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/KeyInfo"
        }
      },
      "role": "admin",
      "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."
    },
    {
      "args": [
        {
          "description": "The key, by its name or its id (bare or as `key_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such key",
          "status": "404"
        },
        {
          "description": "It is rookery's, in use or rotating",
          "status": "409"
        }
      ],
      "group": "keys",
      "http": {
        "method": "DELETE",
        "path": "/v1/keys/{name}"
      },
      "kind": "call",
      "name": "keys.remove",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Remove a key from the ring. Refused for the key rookery, while a host logs in with the key, and while it rotates."
    },
    {
      "args": [
        {
          "description": "The key, by its name or its id (bare or as `key_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such key",
          "status": "404"
        },
        {
          "description": "A rotation runs already",
          "status": "409"
        }
      ],
      "group": "keys",
      "http": {
        "method": "POST",
        "path": "/v1/keys/{name}/rotate"
      },
      "kind": "call",
      "name": "keys.rotate",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Acted"
        }
      },
      "role": "admin",
      "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."
    },
    {
      "args": [],
      "group": "registries",
      "http": {
        "method": "GET",
        "path": "/v1/registries"
      },
      "kind": "call",
      "name": "registries.list",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Registries"
        }
      },
      "role": "admin",
      "summary": "The registries."
    },
    {
      "args": [
        {
          "description": "The registry's name here, or the id of one there is",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "data": {
        "description": "`type`, `url`, and optionally `username` and `repositories`",
        "schema": {}
      },
      "errors": [
        {
          "description": "Not a registry",
          "status": "400"
        }
      ],
      "group": "registries",
      "http": {
        "method": "PUT",
        "path": "/v1/registries/{name}"
      },
      "kind": "call",
      "name": "registries.save",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Add a registry, or change one."
    },
    {
      "args": [
        {
          "description": "A registry, by its name or its id (bare or as `reg_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such registry",
          "status": "404"
        }
      ],
      "group": "registries",
      "http": {
        "method": "DELETE",
        "path": "/v1/registries/{name}"
      },
      "kind": "call",
      "name": "registries.remove",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Remove a registry with its stored login."
    },
    {
      "args": [
        {
          "description": "The registry, by its name or its id (bare or as `reg_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "data": {
        "description": "The new name",
        "schema": {
          "$ref": "#/components/schemas/Rename"
        }
      },
      "errors": [
        {
          "description": "Not a name for a registry",
          "status": "400"
        },
        {
          "description": "No such registry",
          "status": "404"
        },
        {
          "description": "The name is taken",
          "status": "409"
        }
      ],
      "group": "registries",
      "http": {
        "method": "POST",
        "path": "/v1/registries/{name}/rename"
      },
      "kind": "call",
      "name": "registries.rename",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Give a registry another name."
    },
    {
      "args": [
        {
          "description": "A registry, by its name or its id (bare or as `reg_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such registry",
          "status": "404"
        }
      ],
      "group": "registries",
      "http": {
        "method": "POST",
        "path": "/v1/registries/{name}/check"
      },
      "kind": "call",
      "name": "registries.check",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Checked"
        }
      },
      "role": "admin",
      "summary": "Whether a registry answers and takes its login."
    },
    {
      "args": [],
      "group": "settings",
      "http": {
        "method": "GET",
        "path": "/v1/settings"
      },
      "kind": "call",
      "name": "settings.list",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/Setting"
          },
          "type": "array"
        }
      },
      "role": "admin",
      "summary": "The server's settings."
    },
    {
      "args": [
        {
          "description": "The setting",
          "in": "path",
          "name": "key",
          "required": true
        }
      ],
      "data": {
        "description": "The value",
        "schema": {
          "$ref": "#/components/schemas/SettingValue"
        }
      },
      "errors": [
        {
          "description": "This one is set on the server itself",
          "status": "403"
        }
      ],
      "group": "settings",
      "http": {
        "method": "PUT",
        "path": "/v1/settings/{key}"
      },
      "kind": "call",
      "name": "settings.set",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "admin",
      "summary": "Change one of the settings that are open to callers, or any for the user the server runs as."
    },
    {
      "args": [],
      "group": "plugins",
      "http": {
        "method": "GET",
        "path": "/v1/plugins"
      },
      "kind": "call",
      "name": "plugins.list",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/PluginList"
        }
      },
      "role": "admin",
      "summary": "The plugins: those that come with rookery and the server's own."
    },
    {
      "args": [],
      "data": {
        "description": "What to install",
        "schema": {
          "$ref": "#/components/schemas/PluginSpec"
        }
      },
      "errors": [
        {
          "description": "Not a package or address, or npm failed; the message has its output",
          "status": "400"
        }
      ],
      "group": "plugins",
      "http": {
        "method": "POST",
        "path": "/v1/plugins"
      },
      "kind": "call",
      "name": "plugins.add",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/PluginReport"
        }
      },
      "role": "admin",
      "summary": "Install a plugin with npm from a registry or an address."
    },
    {
      "args": [],
      "data": {
        "bytes": true
      },
      "errors": [
        {
          "description": "Not a .tgz, or npm failed; the message has its output",
          "status": "400"
        }
      ],
      "group": "plugins",
      "http": {
        "method": "POST",
        "path": "/v1/plugins/package"
      },
      "kind": "call",
      "name": "plugins.upload",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/PluginReport"
        }
      },
      "role": "admin",
      "summary": "Install a plugin from a .tgz, as npm pack makes one, which the server keeps."
    },
    {
      "args": [
        {
          "description": "The plugin's id",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such plugin",
          "status": "404"
        },
        {
          "description": "It comes with rookery and stays",
          "status": "409"
        }
      ],
      "group": "plugins",
      "http": {
        "method": "DELETE",
        "path": "/v1/plugins/{id}"
      },
      "kind": "call",
      "name": "plugins.remove",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/PluginReport"
        }
      },
      "role": "admin",
      "summary": "Remove one of the server's own plugins."
    },
    {
      "args": [],
      "errors": [
        {
          "description": "npm could not be run",
          "status": "400"
        }
      ],
      "group": "plugins",
      "http": {
        "method": "GET",
        "path": "/v1/plugins/updates"
      },
      "kind": "call",
      "name": "plugins.check",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/PluginUpdates"
        }
      },
      "role": "admin",
      "summary": "Ask the registries the server's own plugins came from whether they have newer versions."
    },
    {
      "args": [],
      "data": {
        "description": "The plugin, by id or npm name; all without one",
        "schema": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/PluginUpdateSpec"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "errors": [
        {
          "description": "It has no registry to ask, comes with rookery, or npm failed; the message says which",
          "status": "400"
        },
        {
          "description": "No such plugin",
          "status": "404"
        }
      ],
      "group": "plugins",
      "http": {
        "method": "POST",
        "path": "/v1/plugins/update"
      },
      "kind": "call",
      "name": "plugins.update",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/PluginReport"
        }
      },
      "role": "admin",
      "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."
    },
    {
      "args": [],
      "group": "setup",
      "http": {
        "method": "GET",
        "path": "/v1/setup"
      },
      "kind": "call",
      "name": "setup.catalogue",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Catalogue"
        }
      },
      "role": "admin",
      "summary": "What a new host starts from, and what plugins can install on one."
    },
    {
      "args": [],
      "data": {
        "description": "What to make",
        "schema": {
          "$ref": "#/components/schemas/Generate"
        }
      },
      "errors": [
        {
          "description": "It could not be made; the message says why",
          "status": "400"
        }
      ],
      "group": "setup",
      "http": {
        "method": "POST",
        "path": "/v1/setup/generate"
      },
      "kind": "call",
      "name": "setup.generate",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Generated"
        }
      },
      "role": "admin",
      "summary": "Make up a host name, or hash or make up a password."
    },
    {
      "args": [],
      "group": "provisioners",
      "http": {
        "method": "GET",
        "path": "/v1/provisioners"
      },
      "kind": "call",
      "name": "provisioners.list",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/ProvisionerInfo"
          },
          "type": "array"
        }
      },
      "role": "view",
      "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."
    },
    {
      "args": [],
      "group": "provisioners",
      "http": {
        "method": "GET",
        "path": "/v1/provisioner-types"
      },
      "kind": "call",
      "name": "provisioners.types",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/ProvisionerInfo"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "The types of provisioner the plugins bring, which a provisioner is registered as."
    },
    {
      "args": [
        {
          "description": "The provisioner, by its name or its id (bare or as `prov_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        },
        {
          "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",
          "header": null,
          "in": "query",
          "name": "arguments",
          "required": false
        }
      ],
      "errors": [
        {
          "description": "No such provisioner",
          "status": "404"
        }
      ],
      "group": "provisioners",
      "http": {
        "method": "GET",
        "path": "/v1/provisioners/{name}"
      },
      "kind": "call",
      "name": "provisioners.get",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/ProvisionerState"
        }
      },
      "role": "view",
      "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."
    },
    {
      "args": [
        {
          "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
        }
      ],
      "data": {
        "description": null,
        "schema": {
          "$ref": "#/components/schemas/SavedProvisioner"
        }
      },
      "errors": [
        {
          "description": "The name, the type or a setting does not fit; the message says which",
          "status": "400"
        }
      ],
      "group": "provisioners",
      "http": {
        "method": "PUT",
        "path": "/v1/provisioners/{name}"
      },
      "kind": "call",
      "name": "provisioners.save",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/ProvisionerInfo"
        }
      },
      "role": "admin",
      "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."
    },
    {
      "args": [
        {
          "description": "Its name or its id (bare or as `prov_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such provisioner",
          "status": "404"
        },
        {
          "description": "It still holds resources; the message names them",
          "status": "409"
        }
      ],
      "group": "provisioners",
      "http": {
        "method": "DELETE",
        "path": "/v1/provisioners/{name}"
      },
      "kind": "call",
      "name": "provisioners.remove",
      "portal": true,
      "result": null,
      "role": "admin",
      "summary": "Forget a registered provisioner, with its settings and the secrets it keeps of its own. It is kept while it holds resources."
    },
    {
      "args": [
        {
          "description": "The provisioner, by its name or its id (bare or as `prov_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such provisioner",
          "status": "404"
        }
      ],
      "group": "provisioners",
      "http": {
        "method": "GET",
        "path": "/v1/provisioners/{name}/actions"
      },
      "kind": "call",
      "name": "provisioners.actions",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/Action"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "What can be done to a provisioner: its plugin's actions, and rookery's own settings of it."
    },
    {
      "args": [
        {
          "description": "The provisioner, by its name or its id (bare or as `prov_ID`)",
          "in": "path",
          "name": "name",
          "required": true
        },
        {
          "description": "The action, as provisioners.actions names it",
          "in": "path",
          "name": "action",
          "required": true
        }
      ],
      "data": {
        "description": "Its arguments, which may also give the provisioner's own for this once, and a token that makes asking again safe",
        "schema": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Act"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "errors": [
        {
          "description": "An argument is missing or unknown, or the body is not one",
          "status": "400"
        },
        {
          "description": "The caller's role is below the action's",
          "status": "403"
        },
        {
          "description": "No such provisioner or action",
          "status": "404"
        },
        {
          "description": "Something else is being done to the provisioner",
          "status": "409"
        },
        {
          "description": "It cannot run here now; the message says why",
          "status": "501"
        },
        {
          "description": "The provisioner failed, as when its engine does not answer",
          "status": "502"
        }
      ],
      "group": "provisioners",
      "http": {
        "method": "POST",
        "path": "/v1/provisioners/{name}/actions/{action}"
      },
      "kind": "call",
      "name": "provisioners.act",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Acted"
        }
      },
      "role": "view",
      "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."
    },
    {
      "args": [
        {
          "description": "Only those of this provisioner, by its name.",
          "header": null,
          "in": "query",
          "name": "provisioner",
          "required": false
        },
        {
          "description": "Only those of this kind, such as `machine` or `deployment`.",
          "header": null,
          "in": "query",
          "name": "kind",
          "required": false
        },
        {
          "description": "Only the machine of this saved host.",
          "header": null,
          "in": "query",
          "name": "host",
          "required": false
        }
      ],
      "group": "resources",
      "http": {
        "method": "GET",
        "path": "/v1/resources"
      },
      "kind": "call",
      "name": "resources.list",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/Resource"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "What provisioners made for rookery, as rookery's records have it. Nothing is asked of the provisioners."
    },
    {
      "args": [],
      "data": {
        "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",
        "schema": {
          "$ref": "#/components/schemas/NewResource"
        }
      },
      "errors": [
        {
          "description": "An argument, a secret or the specification is missing or does not fit; the message says which",
          "status": "400"
        },
        {
          "description": "No such host or provisioner",
          "status": "404"
        },
        {
          "description": "One of that name exists already, or something else is being done to it",
          "status": "409"
        }
      ],
      "group": "resources",
      "http": {
        "method": "POST",
        "path": "/v1/resources"
      },
      "kind": "call",
      "name": "resources.create",
      "portal": true,
      "result": null,
      "role": "admin",
      "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."
    },
    {
      "args": [
        {
          "description": "rookery's id of the resource, bare or as `res_ID`",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such resource",
          "status": "404"
        }
      ],
      "group": "resources",
      "http": {
        "method": "GET",
        "path": "/v1/resources/{id}"
      },
      "kind": "call",
      "name": "resources.get",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Resource"
        }
      },
      "role": "view",
      "summary": "One resource, as its provisioner says it is now. One it no longer finds is `missing`, and its record stays."
    },
    {
      "args": [
        {
          "description": "rookery's id of the resource, bare or as `res_ID`",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "data": {
        "description": "What changes, and a token that makes asking again safe",
        "schema": {
          "$ref": "#/components/schemas/ResourceChange"
        }
      },
      "errors": [
        {
          "description": "An argument, a secret or the specification does not fit",
          "status": "400"
        },
        {
          "description": "No such resource",
          "status": "404"
        },
        {
          "description": "Something else is being done to it",
          "status": "409"
        },
        {
          "description": "Its kind cannot be changed, or it is not made yet",
          "status": "501"
        }
      ],
      "group": "resources",
      "http": {
        "method": "PUT",
        "path": "/v1/resources/{id}"
      },
      "kind": "call",
      "name": "resources.change",
      "portal": true,
      "result": null,
      "role": "admin",
      "summary": "Change a resource, as a job: other values of its kind's arguments, a new specification, other secrets. What is not given stays."
    },
    {
      "args": [
        {
          "description": "rookery's id of the resource, bare or as `res_ID`",
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": "Any text of the caller's; the same again answers with the first job.",
          "header": null,
          "in": "query",
          "name": "token",
          "required": false
        }
      ],
      "errors": [
        {
          "description": "No such resource",
          "status": "404"
        },
        {
          "description": "Something else is being done to it",
          "status": "409"
        },
        {
          "description": "Its provisioner cannot be asked now; the message says why",
          "status": "501"
        }
      ],
      "group": "resources",
      "http": {
        "method": "DELETE",
        "path": "/v1/resources/{id}"
      },
      "kind": "call",
      "name": "resources.remove",
      "portal": true,
      "result": null,
      "role": "admin",
      "summary": "Remove a resource with its provisioner, as a job, and forget it. A host's profile stays."
    },
    {
      "args": [
        {
          "description": "rookery's id of the resource, bare or as `res_ID`",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such resource",
          "status": "404"
        }
      ],
      "group": "resources",
      "http": {
        "method": "GET",
        "path": "/v1/resources/{id}/actions"
      },
      "kind": "call",
      "name": "resources.actions",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/Action"
          },
          "type": "array"
        }
      },
      "role": "view",
      "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."
    },
    {
      "args": [
        {
          "description": "rookery's id of the resource, bare or as `res_ID`",
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": "The action, as resources.actions names it",
          "in": "path",
          "name": "action",
          "required": true
        }
      ],
      "data": {
        "description": "Its arguments, and a token that makes asking again safe",
        "schema": {
          "oneOf": [
            {
              "$ref": "#/components/schemas/Act"
            },
            {
              "type": "null"
            }
          ]
        }
      },
      "errors": [
        {
          "description": "An argument is missing or unknown, or the body is not one",
          "status": "400"
        },
        {
          "description": "The caller's role is below the action's",
          "status": "403"
        },
        {
          "description": "No such resource or action",
          "status": "404"
        },
        {
          "description": "Something else is being done to it",
          "status": "409"
        },
        {
          "description": "It cannot run now; the message says why",
          "status": "501"
        },
        {
          "description": "The provisioner failed",
          "status": "502"
        }
      ],
      "group": "resources",
      "http": {
        "method": "POST",
        "path": "/v1/resources/{id}/actions/{action}"
      },
      "kind": "call",
      "name": "resources.act",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Acted"
        }
      },
      "role": "view",
      "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."
    },
    {
      "args": [
        {
          "description": "rookery's id of the resource, bare or as `res_ID`",
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": "The last so many lines; all when 0 (default 100).",
          "header": null,
          "in": "query",
          "name": "tail",
          "required": false
        }
      ],
      "errors": [
        {
          "description": "Its kind gives no logs, or it is not made yet",
          "status": "400"
        },
        {
          "description": "No such resource",
          "status": "404"
        }
      ],
      "group": "resources",
      "http": {
        "method": "GET",
        "path": "/v1/resources/{id}/logs"
      },
      "kind": "call",
      "name": "resources.logs",
      "portal": true,
      "result": {
        "bytes": true,
        "content_type": "text/plain"
      },
      "role": "operate",
      "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."
    },
    {
      "args": [
        {
          "description": null,
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": "The last so many lines first; all when 0 (default 100).",
          "in": "query",
          "name": "tail",
          "required": false
        }
      ],
      "group": "resources",
      "http": {
        "method": "GET",
        "path": "/v1/resources/{id}/logs"
      },
      "kind": "stream",
      "name": "resources.follow",
      "portal": true,
      "receives": [
        {
          "binary": true,
          "description": "Lines of its log.",
          "example": null,
          "name": "output"
        },
        {
          "binary": false,
          "description": "The log ended, or the provisioner stopped giving it. The last frame; with `error` when it failed.",
          "example": {
            "exited": {
              "exit_code": 0
            }
          },
          "name": "exited"
        }
      ],
      "resumable": false,
      "role": "operate",
      "sends": [],
      "summary": "What a resource writes, as its provisioner gives it, with secrets masked: the last lines, then what follows."
    },
    {
      "args": [
        {
          "description": null,
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": null,
          "in": "path",
          "name": "endpoint",
          "required": true
        }
      ],
      "group": "resources",
      "http": {
        "method": "GET",
        "path": "/v1/resources/{id}/endpoints/{endpoint}"
      },
      "kind": "stream",
      "name": "resources.connect",
      "portal": true,
      "receives": [
        {
          "binary": true,
          "description": "What the endpoint sent.",
          "example": null,
          "name": "bytes"
        },
        {
          "binary": false,
          "description": "The endpoint closed its side. Bytes sent towards it still arrive. The stream ends once both sides have sent this.",
          "example": {
            "eof": true
          },
          "name": "eof"
        }
      ],
      "resumable": false,
      "role": "operate",
      "sends": [
        {
          "binary": true,
          "description": "Bytes for the endpoint.",
          "example": null,
          "name": "bytes"
        },
        {
          "binary": false,
          "description": "The client sends no more, and the endpoint reads the end. What it sends still comes back.",
          "example": {
            "eof": true
          },
          "name": "eof"
        }
      ],
      "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."
    },
    {
      "args": [
        {
          "description": "Only the jobs of this subject: `host:HOST`, `provisioner:PROVISIONER`, `resource:ID` or `installation`, each by name or id.",
          "header": null,
          "in": "query",
          "name": "subject",
          "required": false
        },
        {
          "description": "Only the jobs about this host, by name or id, alone or among others, as a roll-out is.",
          "header": null,
          "in": "query",
          "name": "host",
          "required": false
        },
        {
          "description": "Only the jobs that have not ended, or with `false` only those that have.",
          "header": null,
          "in": "query",
          "name": "running",
          "required": false
        },
        {
          "description": "Only the jobs that started before the job of this id: the next page after it.",
          "header": null,
          "in": "query",
          "name": "before",
          "required": false
        },
        {
          "description": "At most this many (default 100, at most 1,000).",
          "header": null,
          "in": "query",
          "name": "limit",
          "required": false
        }
      ],
      "errors": [
        {
          "description": "`before` names no job",
          "status": "404"
        }
      ],
      "group": "jobs",
      "http": {
        "method": "GET",
        "path": "/v1/jobs"
      },
      "kind": "call",
      "name": "jobs.list",
      "portal": true,
      "result": {
        "schema": {
          "items": {
            "$ref": "#/components/schemas/JobInfo"
          },
          "type": "array"
        }
      },
      "role": "view",
      "summary": "The jobs, newest first."
    },
    {
      "args": [
        {
          "description": "A job's id",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such job",
          "status": "404"
        }
      ],
      "group": "jobs",
      "http": {
        "method": "GET",
        "path": "/v1/jobs/{id}"
      },
      "kind": "call",
      "name": "jobs.get",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/JobInfo"
        }
      },
      "role": "view",
      "summary": "One job's state."
    },
    {
      "args": [
        {
          "description": "A job's id.",
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": "Byte offset to start from.",
          "in": "query",
          "name": "since",
          "required": false
        }
      ],
      "group": "jobs",
      "http": {
        "method": "GET",
        "path": "/v1/jobs/{id}"
      },
      "kind": "stream",
      "name": "jobs.follow",
      "portal": true,
      "receives": [
        {
          "binary": true,
          "description": "The job's output.",
          "example": null,
          "name": "output"
        },
        {
          "binary": false,
          "description": "The job ended. The last frame.",
          "example": {
            "exited": {
              "exit_code": 0
            }
          },
          "name": "exited"
        }
      ],
      "resumable": true,
      "role": "view",
      "sends": [],
      "summary": "A job's output as it is produced."
    },
    {
      "args": [
        {
          "description": "A job's id",
          "in": "path",
          "name": "id",
          "required": true
        },
        {
          "description": "By bytes: start at this offset.",
          "header": null,
          "in": "query",
          "name": "since",
          "required": false
        },
        {
          "description": "By bytes: at most this many (default and most 1 MB).",
          "header": null,
          "in": "query",
          "name": "limit",
          "required": false
        },
        {
          "description": "By lines: start at this line, from 0.",
          "header": null,
          "in": "query",
          "name": "line",
          "required": false
        },
        {
          "description": "By lines: this many (default 100).",
          "header": null,
          "in": "query",
          "name": "count",
          "required": false
        },
        {
          "description": "The last lines.",
          "header": null,
          "in": "query",
          "name": "tail",
          "required": false
        }
      ],
      "errors": [
        {
          "description": "No such job, or its output is not on this machine, as for a job of an installation restored from its store",
          "status": "404"
        }
      ],
      "group": "jobs",
      "http": {
        "method": "GET",
        "path": "/v1/jobs/{id}/output"
      },
      "kind": "call",
      "name": "jobs.output",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Output"
        }
      },
      "role": "view",
      "summary": "What a job wrote, by bytes or by lines."
    },
    {
      "args": [
        {
          "description": "A job's id",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "The caller may not start a job of its kind, so may not stop it",
          "status": "403"
        },
        {
          "description": "No such job",
          "status": "404"
        },
        {
          "description": "It has ended already",
          "status": "409"
        },
        {
          "description": "It runs in another rookery serve of the same store",
          "status": "501"
        }
      ],
      "group": "jobs",
      "http": {
        "method": "POST",
        "path": "/v1/jobs/{id}/stop"
      },
      "kind": "call",
      "name": "jobs.stop",
      "portal": true,
      "result": null,
      "role": "view",
      "summary": "Stop a running job: its programs end, a session it follows ends on its host, and its record says who stopped it."
    },
    {
      "args": [
        {
          "description": "Only this host.",
          "header": null,
          "in": "query",
          "name": "host",
          "required": false
        },
        {
          "description": "Only topics starting with this.",
          "header": null,
          "in": "query",
          "name": "topic",
          "required": false
        },
        {
          "description": "Only messages taken in before this `seq`.",
          "header": null,
          "in": "query",
          "name": "before",
          "required": false
        },
        {
          "description": "Only done ones, or only those that are not.",
          "header": null,
          "in": "query",
          "name": "done",
          "required": false
        },
        {
          "description": "At most this many (default 100, at most 1,000).",
          "header": null,
          "in": "query",
          "name": "limit",
          "required": false
        }
      ],
      "group": "inbox",
      "http": {
        "method": "GET",
        "path": "/v1/inbox"
      },
      "kind": "call",
      "name": "inbox.list",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Inbox"
        }
      },
      "role": "view",
      "summary": "Messages taken in from the hosts' channels."
    },
    {
      "args": [
        {
          "description": "Only this host.",
          "in": "query",
          "name": "host",
          "required": false
        },
        {
          "description": "Only topics starting with this.",
          "in": "query",
          "name": "topic",
          "required": false
        }
      ],
      "group": "inbox",
      "http": {
        "method": "GET",
        "path": "/v1/inbox"
      },
      "kind": "stream",
      "name": "inbox.follow",
      "portal": true,
      "receives": [
        {
          "binary": false,
          "description": "A stored message with its host.",
          "example": {
            "body": {},
            "done": false,
            "from": {
              "level": "agent",
              "uid": 1001
            },
            "host": "server",
            "id": 4812,
            "keep": "log",
            "time": "2026-11-12T10:00:00Z",
            "topic": "myplugin/progress"
          },
          "name": "message"
        },
        {
          "binary": false,
          "description": "This follower was too slow. `events` counts the server's events it missed, of every kind. Read the inbox again.",
          "example": {
            "dropped": {
              "events": 12
            }
          },
          "name": "dropped"
        }
      ],
      "resumable": false,
      "role": "view",
      "sends": [],
      "summary": "Messages as they are taken in from the hosts."
    },
    {
      "args": [
        {
          "description": "The host it came from, by its name or its id",
          "in": "path",
          "name": "host",
          "required": true
        },
        {
          "description": "The message's id on that host",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such message",
          "status": "404"
        }
      ],
      "group": "inbox",
      "http": {
        "method": "POST",
        "path": "/v1/inbox/{host}/{id}/done"
      },
      "kind": "call",
      "name": "inbox.done",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "operate",
      "summary": "Mark a message as done."
    },
    {
      "args": [
        {
          "description": "The host it came from, by its name or its id",
          "in": "path",
          "name": "host",
          "required": true
        },
        {
          "description": "The message's id on that host",
          "in": "path",
          "name": "id",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such message",
          "status": "404"
        }
      ],
      "group": "inbox",
      "http": {
        "method": "DELETE",
        "path": "/v1/inbox/{host}/{id}/done"
      },
      "kind": "call",
      "name": "inbox.reopen",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "operate",
      "summary": "Mark a message as open again."
    },
    {
      "args": [
        {
          "description": "A namespace",
          "in": "path",
          "name": "namespace",
          "required": true
        }
      ],
      "group": "kv",
      "http": {
        "method": "GET",
        "path": "/v1/kv/{namespace}"
      },
      "kind": "call",
      "name": "kv.list",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/KvList"
        }
      },
      "role": "view",
      "summary": "The keys of a namespace with their values."
    },
    {
      "args": [
        {
          "description": "A namespace.",
          "in": "path",
          "name": "namespace",
          "required": true
        }
      ],
      "group": "kv",
      "http": {
        "method": "GET",
        "path": "/v1/kv/{namespace}"
      },
      "kind": "stream",
      "name": "kv.follow",
      "portal": true,
      "receives": [
        {
          "binary": false,
          "description": "A key was written.",
          "example": {
            "key": "layout",
            "revision": 4,
            "value": {
              "columns": 3
            }
          },
          "name": "set"
        },
        {
          "binary": false,
          "description": "A key was removed.",
          "example": {
            "key": "layout",
            "removed": true
          },
          "name": "removed"
        },
        {
          "binary": false,
          "description": "This follower was too slow. `events` counts the server's events it missed, of every kind. List the namespace again.",
          "example": {
            "dropped": {
              "events": 12
            }
          },
          "name": "dropped"
        }
      ],
      "resumable": false,
      "role": "view",
      "sends": [],
      "summary": "Changes to a namespace of the key-value store."
    },
    {
      "args": [
        {
          "description": "A namespace",
          "in": "path",
          "name": "namespace",
          "required": true
        },
        {
          "description": "A key",
          "in": "path",
          "name": "key",
          "required": true
        }
      ],
      "errors": [
        {
          "description": "No such key",
          "status": "404"
        }
      ],
      "group": "kv",
      "http": {
        "method": "GET",
        "path": "/v1/kv/{namespace}/{key}"
      },
      "kind": "call",
      "name": "kv.get",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/KvEntry"
        }
      },
      "role": "view",
      "summary": "One key's value and revision."
    },
    {
      "args": [
        {
          "description": "A namespace",
          "in": "path",
          "name": "namespace",
          "required": true
        },
        {
          "description": "A key",
          "in": "path",
          "name": "key",
          "required": true
        },
        {
          "description": "Write only if the key is at this revision",
          "header": "If-Match",
          "in": "header",
          "name": "if_match",
          "required": false
        },
        {
          "description": "`*`: write only if the key is new",
          "header": "If-None-Match",
          "in": "header",
          "name": "if_none_match",
          "required": false
        }
      ],
      "data": {
        "description": "The value: any JSON, at most 64 KB",
        "schema": {}
      },
      "errors": [
        {
          "description": "Someone else wrote in between",
          "status": "412"
        },
        {
          "description": "The value is too large",
          "status": "413"
        }
      ],
      "group": "kv",
      "http": {
        "method": "PUT",
        "path": "/v1/kv/{namespace}/{key}"
      },
      "kind": "call",
      "name": "kv.set",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/KvWritten"
        }
      },
      "role": "operate",
      "summary": "Write a key, optionally only if nobody wrote in between."
    },
    {
      "args": [
        {
          "description": "A namespace",
          "in": "path",
          "name": "namespace",
          "required": true
        },
        {
          "description": "A key",
          "in": "path",
          "name": "key",
          "required": true
        },
        {
          "description": "Remove only if the key is at this revision",
          "header": "If-Match",
          "in": "header",
          "name": "if_match",
          "required": false
        }
      ],
      "errors": [
        {
          "description": "No such key",
          "status": "404"
        },
        {
          "description": "Someone else wrote in between",
          "status": "412"
        }
      ],
      "group": "kv",
      "http": {
        "method": "DELETE",
        "path": "/v1/kv/{namespace}/{key}"
      },
      "kind": "call",
      "name": "kv.delete",
      "portal": true,
      "result": {
        "schema": {
          "$ref": "#/components/schemas/Done"
        }
      },
      "role": "operate",
      "summary": "Remove a key."
    },
    {
      "args": [],
      "group": "events",
      "http": {
        "method": "GET",
        "path": "/v1/events"
      },
      "kind": "stream",
      "name": "events.follow",
      "portal": true,
      "receives": [
        {
          "binary": false,
          "description": "A message from a host's channel.",
          "example": {
            "host": "server",
            "message": {
              "body": {},
              "from": {
                "level": "host",
                "uid": 0
              },
              "id": 1,
              "keep": "log",
              "time": "2026-11-12T10:00:00Z",
              "topic": "a/b"
            },
            "source": "channel"
          },
          "name": "channel"
        },
        {
          "binary": false,
          "description": "A job started or ended.",
          "example": {
            "job": {
              "action": "apply",
              "host": "server",
              "id": "j1",
              "started": "2026-11-12T10:00:00Z",
              "subject": "host:server"
            },
            "source": "job"
          },
          "name": "job"
        },
        {
          "binary": false,
          "description": "A key changed.",
          "example": {
            "key": "layout",
            "namespace": "ui",
            "revision": 4,
            "source": "kv",
            "value": {}
          },
          "name": "kv"
        },
        {
          "binary": false,
          "description": "A saved host was `added`, `removed`, `renamed` (with the name it had `from`) or its profile `changed`. Read the host itself with hosts.get.",
          "example": {
            "change": "renamed",
            "from": "desk",
            "host": "studio",
            "source": "host"
          },
          "name": "host"
        },
        {
          "binary": false,
          "description": "A resource was `created`, `removed` or its record `changed`. Read it with resources.get.",
          "example": {
            "change": "created",
            "kind": "deployment",
            "provisioner": "docker",
            "resource": "r-k3v9qz2m",
            "source": "resource"
          },
          "name": "resource"
        },
        {
          "binary": false,
          "description": "This follower was too slow. `events` counts the server's events it missed, of every kind. Read what it follows again.",
          "example": {
            "dropped": {
              "events": 12
            }
          },
          "name": "dropped"
        }
      ],
      "resumable": false,
      "role": "view",
      "sends": [
        {
          "binary": false,
          "description": "What to follow. Sent once, first.",
          "example": {
            "changes": [
              "hosts",
              "resources"
            ],
            "hosts": [
              "server"
            ],
            "jobs": true,
            "kv": [
              "ui"
            ],
            "topics": [
              "myplugin/"
            ]
          },
          "name": "follow"
        }
      ],
      "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."
    }
  ],
  "portal": {
    "bytes": 8388608,
    "path": "/v1/portal"
  },
  "title": "rookery serve",
  "version": "0.6.0"
}
