API

Enterprise Frontend API

`GET /spdx/:schematic/:version/:arch`

Note

Enterprise feature: requires Talos Enterprise Image Factory.

Returns an SPDX 2.3 JSON document containing all packages from the Talos and extensions for the given schematic and version. The response is a JSON-encoded SPDX document which can be consumed directly by vulnerability scanners such as grype:

grype sbom:response.spdx.json

SPDX bundles are available for Talos versions v1.11.0 and later.

`GET /vex/:version/vex.json`

Note

Enterprise feature: requires Talos Enterprise Image Factory.

Returns a VEX JSON document containing vulnerability information for all packages in the Talos Linux release. The response is a JSON-encoded VEX document which can be consumed directly by vulnerability scanners such as grype:

grype sbom:talos.spdx.json --vex response.vex.json

`GET /scans/:schematic/:version/:arch/:report`

Note

Enterprise feature: requires Talos Enterprise Image Factory.

Returns a vulnerability scan report for the specified schematic, Talos Linux version and architecture.

Supported report formats:

.json - JSON-encoded report in the format provided by the underlying vulnerability scanner
.table - human-readable table format
.sarif - SARIF format
.cdx - CycloneDX format

HTTP Frontend API

`POST /schematics`

Create a new image schematic.

The request body is a YAML (JSON) encoded schematic description:

customization:
    extraKernelArgs: # optional
        - vga=791
    meta: # optional, allows to set initial Talos META
      - key: 0xa
        value: "{}"
    systemExtensions: # optional
      officialExtensions: # optional
        - siderolabs/gvisor
        - siderolabs/amd-ucode
    secureboot: # optional, only applies to SecureBoot images
       # optional, include well-known UEFI certificates into auto-enrollment database (SecureBoot ISO only)
      includeWellKnownCertificates: true
    bootloader: sd-boot # optional, defaults to auto (bootloader chosen by imager), other options: dual-boot, grub
overlay: # optional
  image: ghcr.io/siderolabs/sbc-raspberry-pi # overlay image
  name: rpi_generic # overlay name
  options: # optional, any valid yaml, depends on the overlay implementation
    data: "mydata"

Output is a JSON object containing the schematic ID and the canonical schematic body as YAML:

{
  "id": "2a63b6e7dab90ec9d44f213339b9545bd39c6499b22a14cf575c1ca4b6e39ff8",
  "schematic": "customization:\n    extraKernelArgs:\n        - vga=791\n"
}

The schematic field is the canonical representation used to compute the ID. Callers should treat it as authoritative, since the factory may modify or add fields to the submitted schematic, for example setting owner for authenticated requests.

This ID can be used to download images with this schematic.

Well-known schematic IDs:

376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba - default schematic (without any customizations)

The schematic in Enterprise edition may contain an owner field, which restricts access to the schematic to the specified owner only. This requires authentication to be enabled. When authentication is enabled, the factory sets owner to the authenticated user. If the request body specifies an owner that does not match the authenticated user, the request is rejected.

`GET /schematics/:schematic`

Retrieve a specific schematic by its ID.

If the schematic is found, the response body contains the YAML-encoded schematic representation. Otherwise a 404 Not Found status code is returned.

`GET /image/:schematic/:version/:path`

Download a Talos Linux boot image with the specified schematic and Talos Linux version.

:schematic is a schematic ID returned by POST /schematic
:version is a Talos Linux version, e.g. v1.5.0
:path is a specific image path (details below)

Common used parameters:

<arch> image architecture: amd64 or arm64
<platform> Talos Linux platform, e.g. metal, aws, gcp, etc.
-secureboot identifies a Secure Boot asset

Supported image paths:

kernel-<arch> (e.g. kernel-amd64) - raw kernel image
cmdline-<platform>-<arch>[-secureboot] (e.g. cmdline-metal-amd64) - kernel command line
initramfs-<arch>.xz (e.g. initramfs-amd64.xz) - initramfs image (including system extensions if configured)
<platform>-<arch>[-secureboot].iso (e.g. metal-amd64.iso) - ISO image
<platform>-<arch>[-secureboot]-uki.efi (e.g. metal-amd64-secureboot-uki.efi) UEFI UKI image (Secure Boot compatible)
installer-<arch>[-secureboot].tar (e.g. installer-amd64.tar) is a custom Talos Linux installer image for metal platform (including system extensions if configured)
<platform>-installer-<arch>[-secureboot].tar (e.g. aws-installer-amd64.tar) is a custom Talos Linux installer image for specific platform (including system extensions if configured)
disk images in different formats (see Talos Linux documentation for a full list):
- metal-<arch>[-secureboot].raw.xz (e.g. metal-amd64.raw.xz) - raw disk image for metal platform
- aws-<arch>.raw.xz (e.g. aws-amd64.raw.xz) - raw disk image for AWS platform, that can be imported as an AMI
- gcp-<arch>.raw.tar.gz (e.g. gcp-amd64.raw.tar.gz) - raw disk image for GCP platform, that can be imported as a GCE image
- ... other support image types

Checksums

Note

Enterprise feature: requires Talos Enterprise Image Factory.

Appending a checksum suffix to any :path returns a checksum file instead of the asset itself.

Suffix	Algorithm	Verify with
`.sha256`	SHA-256	`sha256sum -c`
`.sha512`	SHA-512	`sha512sum -c`

The response is a single line in the standard checksum tool format:

<hexhash>  <filename>

Download an image and verify its integrity:

curl -LO https://factory.talos.dev/image/<schematic>/<version>/metal-amd64.raw.xz
curl -LO https://factory.talos.dev/image/<schematic>/<version>/metal-amd64.raw.xz.sha256
sha256sum -c metal-amd64.raw.xz.sha256

Using curl -JLO (filename from Content-Disposition header):

curl -JLO https://factory.talos.dev/image/<schematic>/<version>/metal-amd64.raw.xz
curl -JLO https://factory.talos.dev/image/<schematic>/<version>/metal-amd64.raw.xz.sha256
sha256sum -c metal-amd64.raw.xz.sha256

With wget:

wget https://factory.talos.dev/image/<schematic>/<version>/metal-amd64.raw.xz
wget https://factory.talos.dev/image/<schematic>/<version>/metal-amd64.raw.xz.sha256
sha256sum -c metal-amd64.raw.xz.sha256

`GET /versions`

Returns a list of Talos Linux versions available for image generation.

["v1.5.0","v1.5.1", "v1.5.2"]

`GET /version/:version/extensions/official`

Returns a list of official system extensions available for the specified Talos Linux version.

[
  {
    "name": "siderolabs/amd-ucode",
    "ref": "ghcr.io/siderolabs/amd-ucode:20230804",
    "digest": "sha256:761a5290a4bae9ceca11468d2ba8ca7b0f94e6e3a107ede2349ae26520682832",
  },

]

`GET /version/:version/overlays/official`

Returns a list of official overlays available for the specified Talos Linux version.

[
  {
    "name": "rpi_generic",
    "image": "siderolabs/sbc-raspberrypi",
    "ref": "ghcr.io/siderolabs/sbc-raspberrypi:v0.1.0",
    "digest": "sha256:849ace01b9af514d817b05a9c5963a35202e09a4807d12f8a3ea83657c76c863",
  },

]

`GET /talosctl/:version`

Returns a list of download URLs for talosctl binaries for the specified Talos Linux version.

:version is a Talos Linux version, e.g. v1.11.0

talosctl downloads are available for Talos versions v1.11.0 and later.

[
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-darwin-amd64",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-darwin-arm64",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-freebsd-amd64",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-freebsd-arm64",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-linux-amd64",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-linux-arm64",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-linux-armv7",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-windows-amd64.exe",
  "https://factory.talos.dev/talosctl/v1.11.0/talosctl-windows-arm64.exe"
]

`GET /talosctl/:version/:path`

Download a talosctl binary for the specified Talos Linux version and platform/architecture.

:version is a Talos Linux version, e.g. v1.11.0
:path is a binary name, e.g. talosctl-linux-amd64 (use GET /talosctl/:version to list available paths)

`GET /secureboot/signing-cert.pem`

Returns PEM-encoded SecureBoot signing certificate used by the Image Factory.

It might be used to manually enroll the certificate into the UEFI firmware. Talos Linux SecureBoot ISOs come with an option for automatic enrollment of the certificate, but if that is not desired, the certificate can be manually enrolled.

PXE Frontend API

The PXE frontend provides an iPXE script that automatically downloads and boots Talos Linux. The bare metal machine should be configured to boot from the URL provided by this API, e.g.:

#!ipxe
chain --replace --autofree https://pxe.talos.dev/pxe/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba/v1.5.0/metal-${buildarch}

`GET /pxe/:schematic/:version/:path`

Returns an iPXE script which downloads and boots Talos Linux with the specified schematic and Talos Linux version, architecture and platform.

:schematic is a schematic ID returned by POST /schematic
:version is a Talos Linux version, e.g. v1.5.0
:path is a <platform>-<arch>[-secureboot] path, e.g. metal-amd64

In non-SecureBoot schematic, the following iPXE script is returned:

#!ipxe
kernel https://pxe.talos.dev/image/:schematic/:version/kernel-<arch> <kernel-cmdline>
initrd https://pxe.talos.dev/image/:schematic/:version/initramfs-<arch>.xz
boot

For SecureBoot schematic, the following iPXE script is returned:

#!ipxe
kernel https://pxe.talos.dev/image/:schematic/:version/<platform>-<arch>-secureboot.uki.efi
boot

OCI Registry Frontend API

The Talos Linux installer image is used for the initial install and upgrades. It can be pulled from the Image Factory OCI registry. If the image hasn't been created yet, it will be built on demand automatically.

Legacy `installer` Image

`docker pull <registry>/installer[-secureboot]/<schematic>:<version>`

Example: docker pull factory.talos.dev/installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:v1.5.0

`installer` Image

`docker pull <registry>/<platform>-installer[-secureboot]/<version>`

Examples:

docker pull factory.talos.dev/metal-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:v1.5.0
docker pull factory.talos.dev/aws-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:v1.5.0

Pulls the Talos Linux installer image with the specified schematic and Talos Linux version. The image platform (architecture) will be determined by the architecture of the Talos Linux Linux machine.

`latest` Tag Resolution

The latest tag automatically resolves to the latest stable (non-prerelease) Talos Linux version available:

docker pull factory.talos.dev/metal-installer/376567988ad370138ad8b2698212367b8edcb69b5fd68c80be1f2ec7d603b4ba:latest

This is equivalent to pulling with an explicit stable version, ensuring that prerelease versions (e.g. v1.5.0-alpha.1) are not used.

`GET /oci/cosign/signing-key.pub`

Returns PEM-encoded public key used to sign the Talos Linux installer images.

The key can be used to verify the installer images with cosign:

cosign verify --offline --insecure-ignore-tlog --insecure-ignore-sct --key signing-key.pub factory.talos.dev/...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API

Enterprise Frontend API

`GET /spdx/:schematic/:version/:arch`

`GET /vex/:version/vex.json`

`GET /scans/:schematic/:version/:arch/:report`

HTTP Frontend API

`POST /schematics`

`GET /schematics/:schematic`

`GET /image/:schematic/:version/:path`

Checksums

`GET /versions`

`GET /version/:version/extensions/official`

`GET /version/:version/overlays/official`

`GET /talosctl/:version`

`GET /talosctl/:version/:path`

`GET /secureboot/signing-cert.pem`

PXE Frontend API

`GET /pxe/:schematic/:version/:path`

OCI Registry Frontend API

Legacy `installer` Image

`docker pull <registry>/installer[-secureboot]/<schematic>:<version>`

`installer` Image

`docker pull <registry>/<platform>-installer[-secureboot]/<version>`

`latest` Tag Resolution

`GET /oci/cosign/signing-key.pub`

FilesExpand file tree

api.md

Latest commit

History

api.md

File metadata and controls

API

Enterprise Frontend API

GET /spdx/:schematic/:version/:arch

GET /vex/:version/vex.json

GET /scans/:schematic/:version/:arch/:report

HTTP Frontend API

POST /schematics

GET /schematics/:schematic

GET /image/:schematic/:version/:path

Checksums

GET /versions

GET /version/:version/extensions/official

GET /version/:version/overlays/official

GET /talosctl/:version

GET /talosctl/:version/:path

GET /secureboot/signing-cert.pem

PXE Frontend API

GET /pxe/:schematic/:version/:path

OCI Registry Frontend API

Legacy installer Image

docker pull <registry>/installer[-secureboot]/<schematic>:<version>

installer Image

docker pull <registry>/<platform>-installer[-secureboot]/<version>

latest Tag Resolution

GET /oci/cosign/signing-key.pub

`GET /spdx/:schematic/:version/:arch`

`GET /vex/:version/vex.json`

`GET /scans/:schematic/:version/:arch/:report`

`POST /schematics`

`GET /schematics/:schematic`

`GET /image/:schematic/:version/:path`

`GET /versions`

`GET /version/:version/extensions/official`

`GET /version/:version/overlays/official`

`GET /talosctl/:version`

`GET /talosctl/:version/:path`

`GET /secureboot/signing-cert.pem`

`GET /pxe/:schematic/:version/:path`

Legacy `installer` Image

`docker pull <registry>/installer[-secureboot]/<schematic>:<version>`

`installer` Image

`docker pull <registry>/<platform>-installer[-secureboot]/<version>`

`latest` Tag Resolution

`GET /oci/cosign/signing-key.pub`