openapi: 3.1.0
info:
  title: systemd-machined (org.freedesktop.machine1)
  version: '1.0'
  summary: D-Bus API of systemd-machined modeled as REST operations.
  description: |
    Documentation/contract artifact for the `org.freedesktop.machine1` D-Bus interface set on the
    system bus, exposed by systemd-machined. Tracks local containers and virtual machines
    registered with the system, lists/inspects/imports machine images, opens shells inside
    containers, and copies files in/out across container boundaries.
  license: { name: LGPL-2.1-or-later, url: https://github.com/systemd/systemd/blob/main/LICENSES/LGPL-2.1-or-later.txt }
servers: [{ url: 'dbus://system/org.freedesktop.machine1' }]
tags:
- name: Machines
- name: Images
paths:
  /machines:
    get:
      tags: [Machines]
      operationId: ListMachines
      summary: List All Registered Machines
      description: Mirrors `ListMachines()`. Returns (name, class, service, object path) tuples.
      responses: { '200': { description: Array of machines., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Machine' } } } } } }
  /machines/{name}:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    get:
      tags: [Machines]
      operationId: GetMachine
      summary: Get A Machine By Name
      description: Mirrors `GetMachine(name)`.
      responses: { '200': { description: Machine object path. } }
  /machines/{name}/terminate:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Machines]
      operationId: TerminateMachine
      summary: Terminate A Machine
      description: Mirrors `TerminateMachine(name)`.
      responses: { '204': { description: Terminated. } }
  /machines/{name}/kill:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Machines]
      operationId: KillMachine
      summary: Send A Signal To A Machine
      description: Mirrors `KillMachine(name, who, signal)`.
      requestBody: { content: { application/json: { schema: { type: object, properties: { who: { type: string, enum: [all, leader] }, signal: { type: integer } } } } } }
      responses: { '204': { description: Signal sent. } }
  /machines/{name}/open-shell:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Machines]
      operationId: OpenMachineShell
      summary: Open A Shell Inside A Machine
      description: Mirrors `OpenMachineShell(name, user, path, args, env)`. Returns a PTY FD.
      responses: { '200': { description: PTY FD info. } }
  /machines/{name}/copy-from:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Machines]
      operationId: CopyFromMachine
      summary: Copy A File Out Of A Machine
      description: Mirrors `CopyFromMachine(name, src, dest)`.
      responses: { '204': { description: Copied. } }
  /machines/{name}/copy-to:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Machines]
      operationId: CopyToMachine
      summary: Copy A File Into A Machine
      description: Mirrors `CopyToMachine(name, src, dest)`.
      responses: { '204': { description: Copied. } }
  /images:
    get:
      tags: [Images]
      operationId: ListImages
      summary: List All Machine Images
      description: Mirrors `ListImages()` on the Manager.
      responses: { '200': { description: Array of images., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Image' } } } } } }
  /images/{name}:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    delete:
      tags: [Images]
      operationId: RemoveImage
      summary: Remove A Machine Image
      description: Mirrors `RemoveImage(name)`.
      responses: { '204': { description: Removed. } }
  /images/{name}/clone:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Images]
      operationId: CloneImage
      summary: Clone A Machine Image
      description: Mirrors `CloneImage(src, dest, read_only)`.
      requestBody: { content: { application/json: { schema: { type: object, properties: { dest: { type: string }, read_only: { type: boolean } } } } } }
      responses: { '204': { description: Cloned. } }
  /images/{name}/rename:
    parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
    post:
      tags: [Images]
      operationId: RenameImage
      summary: Rename A Machine Image
      description: Mirrors `RenameImage(src, dest)`.
      responses: { '204': { description: Renamed. } }
components:
  schemas:
    Machine:
      type: object
      properties:
        name: { type: string }
        class: { type: string, enum: [vm, container] }
        service: { type: string, description: 'Service that registered the machine (e.g. systemd-nspawn, libvirt).' }
        object_path: { type: string }
    Image:
      type: object
      properties:
        name: { type: string }
        type: { type: string, enum: [directory, subvolume, raw, block] }
        read_only: { type: boolean }
        ctime: { type: integer }
        mtime: { type: integer }
        usage: { type: integer }
        object_path: { type: string }