{
  "components": {
    "responses": {
      "Error": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Error"
      }
    },
    "schemas": {
      "Alias": {
        "description": "A release alias.\n\nKnown values:\n\n- `latest`: The newest generally-available release. Never a pre-release.\n- `lts`: The newest release the vendor itself labels long-term support. Absent for vendors that do not use that label.\n- `dev`: The vendor's development channel (see the distro's `dev_channel`).",
        "oneOf": [
          {
            "enum": [
              "latest",
              "lts",
              "dev"
            ],
            "type": "string"
          },
          {
            "pattern": "^(?!(?:latest|lts|dev)$)",
            "type": "string"
          }
        ]
      },
      "Artifact": {
        "description": "One downloadable image file of a build. Within a build an artifact is identified by `variant / arch / format`.",
        "properties": {
          "arch": {
            "description": "Architecture, using osinfo-db names (`x86_64`, `aarch64`, ...).",
            "type": "string"
          },
          "compression": {
            "$ref": "#/components/schemas/Compression"
          },
          "datasources": {
            "default": [],
            "description": "cloud-init datasources (or compatible implementations) the image is known to support, using cloud-init's lowercase names (e.g. `nocloud`). Empty when unknown.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "default_variant": {
            "description": "Whether this is the vendor's default variant.",
            "nullable": true,
            "type": "boolean"
          },
          "firmware": {
            "default": [],
            "description": "Firmware the image is known to boot with. Empty when unknown.",
            "items": {
              "$ref": "#/components/schemas/Firmware"
            },
            "type": "array"
          },
          "format": {
            "$ref": "#/components/schemas/ImageFormat"
          },
          "integrity": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Integrity"
              }
            ],
            "nullable": true
          },
          "locations": {
            "description": "Where the file can be downloaded. Current builds have a `primary` location; archived builds have none.",
            "items": {
              "$ref": "#/components/schemas/Location"
            },
            "type": "array"
          },
          "size": {
            "description": "Size in bytes of the file as downloaded, when known.",
            "format": "uint64",
            "minimum": 0,
            "nullable": true,
            "type": "integer"
          },
          "ssh_key_injection": {
            "description": "Whether the image accepts SSH public keys from instance metadata. Absent means unknown, not true.",
            "nullable": true,
            "type": "boolean"
          },
          "variant": {
            "description": "The vendor's flavour of the image (e.g. `server`, `base`, `lvm`, `genericcloud`, `nocloud`).",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "arch",
          "compression",
          "format",
          "locations"
        ],
        "type": "object"
      },
      "Build": {
        "description": "One vendor build. A build is identified by `distro / release / build`, never by its URL.",
        "properties": {
          "artifacts": {
            "items": {
              "$ref": "#/components/schemas/Artifact"
            },
            "type": "array"
          },
          "build": {
            "description": "The vendor's build id or serial (e.g. `20260927`, `9.8-20260525.0`, `v1.14.2`).",
            "type": "string"
          },
          "first_seen": {
            "description": "When the index first recorded this build.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "osinfo": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OsinfoRef"
              }
            ],
            "description": "Overrides the release's osinfo reference when osinfo-db has a more specific entry for this build's point release. Not yet populated (see the release's `osinfo`).",
            "nullable": true
          },
          "point_release": {
            "description": "Vendor point release this build belongs to, for distros that have them (e.g. `9.8`).",
            "nullable": true,
            "type": "string"
          },
          "published_at": {
            "description": "When the vendor published the build, if the vendor says.",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "artifacts",
          "build"
        ],
        "type": "object"
      },
      "BuildList": {
        "description": "The builds of one release. Used for `v1/distros/<distro>/releases/<release>/index.json` (builds in the vendor's main tree), `.../archive.json` (builds that survive only in a vendor vault), and the alias files under `v1/distros/<distro>/aliases/`, which are a copy of the aliased release's `index.json`.",
        "properties": {
          "builds": {
            "description": "Newest first.",
            "items": {
              "$ref": "#/components/schemas/Build"
            },
            "type": "array"
          },
          "distro": {
            "type": "string"
          },
          "release": {
            "type": "string"
          }
        },
        "required": [
          "builds",
          "distro",
          "release"
        ],
        "type": "object"
      },
      "ChecksumFormat": {
        "description": "Layout of a vendor document that contains a hash.\n\nKnown values:\n\n- `gnu`: GNU coreutils style: `<hex>  [*]<filename>` per line.\n- `bsd`: BSD style: `SHA256 (<filename>) = <hex>` per line.\n- `bare`: The file contains only the hex hash.\n- `vendor_document`: Hash appears in a vendor document with no generic format (for example a JSON feed or an HTML page); re-checking it needs vendor-specific parsing.",
        "oneOf": [
          {
            "enum": [
              "gnu",
              "bsd",
              "bare",
              "vendor_document"
            ],
            "type": "string"
          },
          {
            "pattern": "^(?!(?:gnu|bsd|bare|vendor_document)$)",
            "type": "string"
          }
        ]
      },
      "ChecksumSource": {
        "description": "A vendor document that contains the artifact's hash.",
        "properties": {
          "filename": {
            "description": "The name the file is listed under in the checksum document, for formats that list several files (`gnu`, `bsd`). Null for `bare` and `vendor_document`.",
            "nullable": true,
            "type": "string"
          },
          "format": {
            "$ref": "#/components/schemas/ChecksumFormat"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "format",
          "url"
        ],
        "type": "object"
      },
      "Compression": {
        "description": "Compression applied to the file as downloaded.\n\nKnown values:\n\n- `none`\n- `gzip`\n- `xz`\n- `zstd`\n- `bzip2`",
        "oneOf": [
          {
            "enum": [
              "none",
              "gzip",
              "xz",
              "zstd",
              "bzip2"
            ],
            "type": "string"
          },
          {
            "pattern": "^(?!(?:none|gzip|xz|zstd|bzip2)$)",
            "type": "string"
          }
        ]
      },
      "Digest": {
        "description": "A hash of the artifact as published by the vendor.",
        "properties": {
          "algorithm": {
            "$ref": "#/components/schemas/DigestAlgorithm"
          },
          "source": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ChecksumSource"
              }
            ],
            "description": "Where the vendor publishes this hash, so a client can re-check it.",
            "nullable": true
          },
          "value": {
            "description": "Lowercase hex.",
            "type": "string"
          }
        },
        "required": [
          "algorithm",
          "value"
        ],
        "type": "object"
      },
      "DigestAlgorithm": {
        "enum": [
          "sha256",
          "sha512"
        ],
        "type": "string"
      },
      "Distro": {
        "description": "`v1/distros/<distro>/index.json`: a distro and its releases, newest first.",
        "properties": {
          "dev_channel": {
            "description": "The vendor's name for the channel the `dev` alias follows (e.g. `bloody`, `sid`, `rawhide`, `edge`). Null when the vendor has no development channel in the index.",
            "nullable": true,
            "type": "string"
          },
          "homepage": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "nullable": true,
            "type": "string"
          },
          "os_family": {
            "$ref": "#/components/schemas/OsFamily"
          },
          "releases": {
            "items": {
              "$ref": "#/components/schemas/Release"
            },
            "type": "array"
          }
        },
        "required": [
          "id",
          "os_family",
          "releases"
        ],
        "type": "object"
      },
      "DistroList": {
        "description": "`v1/index.json`: every distro in the index.",
        "properties": {
          "distros": {
            "items": {
              "$ref": "#/components/schemas/DistroSummary"
            },
            "type": "array"
          }
        },
        "required": [
          "distros"
        ],
        "type": "object"
      },
      "DistroSummary": {
        "description": "One distro as listed in `v1/index.json`.",
        "properties": {
          "homepage": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "description": "Our short name for the distro, also its directory name (e.g. `ubuntu`, `rocky`, `centos-stream`).",
            "type": "string"
          },
          "name": {
            "description": "Human-facing name (e.g. `Rocky Linux`).",
            "nullable": true,
            "type": "string"
          },
          "os_family": {
            "$ref": "#/components/schemas/OsFamily"
          }
        },
        "required": [
          "id",
          "os_family"
        ],
        "type": "object"
      },
      "Error": {
        "description": "Error information from a response.",
        "properties": {
          "error_code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "message",
          "request_id"
        ],
        "type": "object"
      },
      "Firmware": {
        "enum": [
          "bios",
          "uefi"
        ],
        "type": "string"
      },
      "HttpMetadata": {
        "description": "Response metadata the vendor's server reported for the file.",
        "properties": {
          "etag": {
            "description": "`ETag`, verbatim. Opaque: not a content hash.",
            "nullable": true,
            "type": "string"
          },
          "last_modified": {
            "description": "`Last-Modified`, verbatim.",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ImageFormat": {
        "description": "Disk image format of the file, once decompressed.\n\nKnown values:\n\n- `qcow2`\n- `raw`\n- `vmdk`",
        "oneOf": [
          {
            "enum": [
              "qcow2",
              "raw",
              "vmdk"
            ],
            "type": "string"
          },
          {
            "pattern": "^(?!(?:qcow2|raw|vmdk)$)",
            "type": "string"
          }
        ]
      },
      "Integrity": {
        "description": "Everything the vendor offers for checking a download. Clients choose which of it to use, and whether to re-fetch it from the vendor rather than trust the copy here.",
        "properties": {
          "digests": {
            "default": [],
            "description": "Hashes as read from the vendor. Empty when the vendor publishes none.",
            "items": {
              "$ref": "#/components/schemas/Digest"
            },
            "type": "array"
          },
          "http": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HttpMetadata"
              }
            ],
            "description": "HTTP metadata the vendor's server reported for the file. Useful mostly when there are no digests.",
            "nullable": true
          },
          "signatures": {
            "default": [],
            "description": "Vendor signatures over the checksum documents or the image.",
            "items": {
              "$ref": "#/components/schemas/Signature"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "Location": {
        "description": "A download location for an artifact.",
        "properties": {
          "kind": {
            "allOf": [
              {
                "$ref": "#/components/schemas/LocationKind"
              }
            ],
            "description": "Which kind of location this is. The index always says; clients should not depend on it, since a minimal client just downloads the first location.",
            "nullable": true
          },
          "redirects_off_host": {
            "description": "Whether the vendor answers `url` with a redirect to a different host: a mirror network, or a CDN such as GitHub's asset host. The host itself is not recorded because mirror redirectors pick a different one per request.",
            "nullable": true,
            "type": "boolean"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      },
      "LocationKind": {
        "oneOf": [
          {
            "description": "The vendor's main download tree.",
            "enum": [
              "primary"
            ],
            "type": "string"
          },
          {
            "description": "A vendor archive of builds no longer in the main tree.",
            "enum": [
              "vault"
            ],
            "type": "string"
          },
          {
            "description": "A mirror the vendor names.",
            "enum": [
              "mirror"
            ],
            "type": "string"
          }
        ]
      },
      "OsFamily": {
        "enum": [
          "linux",
          "bsd",
          "illumos"
        ],
        "type": "string"
      },
      "OsinfoRef": {
        "description": "A cross-reference to an osinfo-db OS entry (<https://gitlab.com/libosinfo/osinfo-db>).",
        "properties": {
          "id": {
            "description": "Full osinfo id (e.g. `http://ubuntu.com/ubuntu/24.04`).",
            "type": "string"
          },
          "short_id": {
            "description": "The entry's primary short id (e.g. `ubuntu24.04`), as accepted by `virt-install --osinfo`.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "short_id"
        ],
        "type": "object"
      },
      "Release": {
        "description": "One release of a distro. A release is the vendor's major release or series (`noble`, `9`, `trixie`); point releases are recorded on builds.",
        "properties": {
          "aliases": {
            "default": [],
            "description": "Aliases this release currently holds. Each alias is held by at most one release of a distro, and has a file of the same name (`latest.json`, `lts.json`, `dev.json`) in the distro's `aliases/` directory.",
            "items": {
              "$ref": "#/components/schemas/Alias"
            },
            "type": "array"
          },
          "eol_date": {
            "description": "The vendor's end-of-support date, when published.",
            "format": "date",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "description": "Release token, also the release's directory name (e.g. `noble`, `9`, `1.14`). For vendors that publish channels rather than releases it is what the channel resolved to (OmniOS `r151058`, Arch `rolling`).",
            "type": "string"
          },
          "osinfo": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OsinfoRef"
              }
            ],
            "description": "Matching osinfo-db entry, when one exists. Not yet populated: see <https://github.com/TritonDataCenter/cloud-image-index/blob/main/docs/design.md#osinfo-db-cross-references>.",
            "nullable": true
          },
          "title": {
            "description": "Human-facing title (e.g. `24.04 LTS Noble Numbat`).",
            "nullable": true,
            "type": "string"
          },
          "version": {
            "description": "Vendor version string (e.g. `24.04`, `9`, `1.14`).",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      },
      "Signature": {
        "description": "A vendor OpenPGP signature over a checksum document or over the image itself (see `signs`).",
        "properties": {
          "key_url": {
            "description": "Where the vendor publishes the signing key, when known.",
            "nullable": true,
            "type": "string"
          },
          "kind": {
            "$ref": "#/components/schemas/SignatureKind"
          },
          "signs": {
            "description": "URL of what the signature covers: a checksum document, or the image itself (e.g. Alpine).",
            "type": "string"
          },
          "url": {
            "description": "URL of the signature itself.",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "signs",
          "url"
        ],
        "type": "object"
      },
      "SignatureKind": {
        "description": "Kind of vendor signature.\n\nKnown values:\n\n- `pgp_detached`: Detached OpenPGP signature.\n- `pgp_clearsigned`: OpenPGP clear-signed document; `url` and `signs` are the same.",
        "oneOf": [
          {
            "enum": [
              "pgp_detached",
              "pgp_clearsigned"
            ],
            "type": "string"
          },
          {
            "pattern": "^(?!(?:pgp_detached|pgp_clearsigned)$)",
            "type": "string"
          }
        ]
      }
    }
  },
  "info": {
    "title": "cloud-image-index",
    "version": "1.0.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/v1/distros/{distro}/aliases/dev.json": {
      "get": {
        "description": "Not found for distros with no development channel in the index.",
        "operationId": "alias_dev",
        "parameters": [
          {
            "in": "path",
            "name": "distro",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuildList"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "The builds of the release holding the `dev` alias."
      }
    },
    "/v1/distros/{distro}/aliases/latest.json": {
      "get": {
        "operationId": "alias_latest",
        "parameters": [
          {
            "in": "path",
            "name": "distro",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuildList"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "The builds of the release holding the `latest` alias."
      }
    },
    "/v1/distros/{distro}/aliases/lts.json": {
      "get": {
        "description": "Not found for distros whose vendor has no LTS label.",
        "operationId": "alias_lts",
        "parameters": [
          {
            "in": "path",
            "name": "distro",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuildList"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "The builds of the release holding the `lts` alias."
      }
    },
    "/v1/distros/{distro}/index.json": {
      "get": {
        "operationId": "distro",
        "parameters": [
          {
            "in": "path",
            "name": "distro",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Distro"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "One distro and its releases."
      }
    },
    "/v1/distros/{distro}/releases/{release}/archive.json": {
      "get": {
        "description": "The final build of each end-of-life point release.",
        "operationId": "release_archive",
        "parameters": [
          {
            "in": "path",
            "name": "distro",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "release",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuildList"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Archived builds of a release, available only from a vendor vault."
      }
    },
    "/v1/distros/{distro}/releases/{release}/index.json": {
      "get": {
        "operationId": "release_builds",
        "parameters": [
          {
            "in": "path",
            "name": "distro",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "release",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BuildList"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Current builds of a release, from the vendor's main tree."
      }
    },
    "/v1/index.json": {
      "get": {
        "operationId": "distro_list",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistroList"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Every distro in the index."
      }
    },
    "/v1/openapi.json": {
      "get": {
        "description": "As generated by the version of the index that wrote the tree.",
        "operationId": "openapi",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "This OpenAPI document."
      }
    }
  }
}