openapi: 3.2.0
info:
  title: Ubicloud Machine Image API
  version: 0.1.0
  contact:
    url: https://www.ubicloud.com/
    email: support@ubicloud.com
  license:
    name: GNU Affero General Public License v3.0 (AGPL-3.0)
    url: https://www.gnu.org/licenses/agpl-3.0.en.html
  description: 'Operations tagged Machine Image across 2 of this provider''s published API definitions: ubicloud-openapi.yml, ubicloud-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ubicloud.com
security:
- BearerAuth: []
tags:
- description: Machine Image Operations
  name: Machine Image
paths:
  /project/{project_id}/location/{location}/machine-image:
    get:
      operationId: listLocationMachineImages
      summary: List machine images in a location
      parameters:
      - $ref: '#/components/parameters/location'
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/start_after'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/MachineImages'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    post:
      operationId: createMachineImage
      summary: Create a machine image from a stopped VM
      parameters:
      - $ref: '#/components/parameters/machine_image_new_name'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vm:
                  description: UBID of the source VM
                  type: string
                version:
                  description: Version label (default is a timestamp)
                  type: string
                destroy_source:
                  description: Destroy the source VM after capture
                  type: boolean
              additionalProperties: false
              required:
              - vm
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    delete:
      operationId: deleteMachineImage
      summary: Delete a machine image
      parameters:
      - $ref: '#/components/parameters/machine_image_reference'
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    get:
      operationId: getMachineImage
      summary: Get details of a machine image
      parameters:
      - $ref: '#/components/parameters/machine_image_reference'
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    patch:
      operationId: updateMachineImage
      summary: Update a machine image
      parameters:
      - $ref: '#/components/parameters/machine_image_reference'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                latest_version:
                  description: Version label to set as latest
                  type: string
              additionalProperties: false
              required:
              - latest_version
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}/rename:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/machine_image_reference'
    post:
      operationId: renameMachineImage
      summary: Rename a machine image
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: New name for the machine image
                  type: string
              additionalProperties: false
              required:
              - name
      responses:
        '200':
          $ref: '#/components/responses/MachineImage'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}/version:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/machine_image_reference'
    get:
      operationId: listMachineImageVersions
      summary: List versions of a machine image
      responses:
        '200':
          $ref: '#/components/responses/MachineImageVersions'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/location/{location}/machine-image/{machine_image_reference}/version/{version}:
    parameters:
    - $ref: '#/components/parameters/project_id'
    - $ref: '#/components/parameters/location'
    - $ref: '#/components/parameters/machine_image_reference'
    - $ref: '#/components/parameters/machine_image_version'
    post:
      operationId: createMachineImageVersion
      summary: Create a new version of a machine image from a stopped VM
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vm:
                  description: UBID of the source VM
                  type: string
                destroy_source:
                  description: Destroy the source VM after capture
                  type: boolean
              additionalProperties: false
              required:
              - vm
      responses:
        '200':
          $ref: '#/components/responses/MachineImageVersion'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    delete:
      operationId: deleteMachineImageVersion
      summary: Delete a specific version of a machine image
      responses:
        '204':
          $ref: '#/components/responses/Delete'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    servers:
    - url: https://api.ubicloud.com
  /project/{project_id}/machine-image:
    get:
      operationId: listProjectMachineImages
      summary: List all machine images
      parameters:
      - $ref: '#/components/parameters/project_id'
      - $ref: '#/components/parameters/start_after'
      - $ref: '#/components/parameters/page_size'
      - $ref: '#/components/parameters/order_column'
      responses:
        '200':
          $ref: '#/components/responses/MachineImages'
        default:
          $ref: '#/components/responses/Error'
      tags:
      - Machine Image
    servers:
    - url: https://api.ubicloud.com
components:
  responses:
    MachineImageVersion:
      description: A machine image version
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineImageVersion'
      x-go-name: MachineImageVersionResponse
    Delete:
      description: An empty response after successful resource delete
    MachineImageVersions:
      description: A list of machine image versions
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MachineImageVersion'
            additionalProperties: false
            required:
            - count
            - items
    MachineImage:
      description: A machine image
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MachineImage'
    Error:
      description: An error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    MachineImages:
      description: A list of machine images
      content:
        application/json:
          schema:
            type: object
            properties:
              count:
                type: integer
              items:
                type: array
                items:
                  $ref: '#/components/schemas/MachineImage'
            additionalProperties: false
            required:
            - count
            - items
  parameters:
    location:
      description: The Ubicloud location/region
      in: path
      name: location
      required: true
      schema:
        type: string
        example: eu-central-h1
    machine_image_version:
      description: Version label of the machine image
      example: v1.0
      in: path
      name: version
      required: true
      schema:
        type: string
        pattern: ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$
    machine_image_reference:
      description: Machine Image ID or name
      examples:
        id:
          value: m1n30gjk1d1e2jj34v9x0dq4rp
        name:
          value: my-image
      in: path
      name: machine_image_reference
      required: true
      schema:
        $ref: '#/components/schemas/Reference'
    project_id:
      description: ID of the project
      in: path
      name: project_id
      required: true
      schema:
        type: string
        example: pjkkmx0f2vke4h36nk9cm8v8q0
        pattern: ^pj[0-9a-hj-km-np-tv-z]{24}$
    order_column:
      description: Pagination - Order column
      in: query
      name: order_column
      required: false
      schema:
        type: string
        default: id
    start_after:
      description: Pagination - Start after
      in: query
      name: start_after
      required: false
      schema:
        type: string
    page_size:
      description: Pagination - Page size
      in: query
      name: page_size
      required: false
      schema:
        type: integer
        default: 10
    machine_image_new_name:
      description: Name for a new machine image (UBID format not allowed)
      example: my-image
      in: path
      name: machine_image_reference
      required: true
      schema:
        type: string
        pattern: ^(?!m1[0-9a-hj-km-np-tv-z]{24}$)[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          additionalProperties: false
          properties:
            code:
              type: integer
              example: 401
            message:
              type: string
              example: There was an error logging in
            type:
              type: string
              example: InvalidCredentials
            details:
              type:
              - object
              - 'null'
          required:
          - code
          - message
          - type
      additionalProperties: false
      required:
      - error
    Reference:
      description: Resource ID or name
      type: string
      pattern: ^[a-z0-9](?:[a-z0-9\-]{0,61}[a-z0-9])?$
    MachineImage:
      type: object
      properties:
        id:
          description: ID of the machine image
          type: string
          example: m1n30gjk1d1e2jj34v9x0dq4rp
          pattern: ^m1[0-9a-hj-km-np-tv-z]{24}$
        name:
          description: Name of the machine image
          type: string
          example: my-image
        location:
          description: Location of the machine image
          type: string
          example: eu-central-h1
        arch:
          description: Architecture
          type: string
          enum:
          - x64
          - arm64
        latest_version:
          description: Latest version label
          type:
          - string
          - 'null'
        created_at:
          description: Creation timestamp
          type: string
          format: date-time
      additionalProperties: false
      required:
      - id
      - name
      - location
      - arch
      - created_at
    MachineImageVersion:
      type: object
      properties:
        id:
          description: ID of the machine image version
          type: string
          example: mvn30gjk1d1e2jj34v9x0dq4rp
        version:
          description: Version label
          type: string
          example: v1.0
        state:
          description: Lifecycle state, or null if no metal record exists
          type:
          - string
          - 'null'
          enum:
          - creating
          - ready
          - destroying
          - failed
        actual_size_mib:
          description: Actual size of the image in MiB
          type:
          - integer
          - 'null'
        archive_size_mib:
          description: Size of the archived image in MiB
          type:
          - integer
          - 'null'
        created_at:
          description: Creation timestamp
          type: string
          format: date-time
        latest:
          description: True if this is the machine image's currently-published latest version
          type: boolean
      additionalProperties: false
      required:
      - id
      - version
      - state
      - created_at
      - latest
      x-go-name: MachineImageVersionSchema
  securitySchemes:
    BearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
x-refined-from:
- ubicloud-openapi.yml
- ubicloud-openapi.yml