modeling-app/openapi/machine-api.json

{
  "components": {
    "responses": {
      "Error": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Error"
      }
    },
    "schemas": {
      "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"
      },
      "ExtraMachineInfoResponse": {
        "description": "Extra machine-specific information regarding a connected machine.",
        "oneOf": [
          {
            "properties": {
              "type": {
                "enum": [
                  "moonraker"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "properties": {
              "type": {
                "enum": [
                  "usb"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "properties": {
              "current_stage": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Stage"
                  }
                ],
                "description": "The current stage of the machine as defined by Bambu which can include errors, etc.",
                "nullable": true
              },
              "nozzle_diameter": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/NozzleDiameter"
                  }
                ],
                "description": "The nozzle diameter of the machine."
              },
              "type": {
                "enum": [
                  "bambu"
                ],
                "type": "string"
              }
            },
            "required": [
              "nozzle_diameter",
              "type"
            ],
            "type": "object"
          }
        ]
      },
      "FdmHardwareConfiguration": {
        "description": "Configuration for a FDM-based printer.",
        "properties": {
          "filaments": {
            "description": "The filaments the printer has access to.",
            "items": {
              "$ref": "#/components/schemas/Filament"
            },
            "type": "array"
          },
          "loaded_filament_idx": {
            "description": "The currently loaded filament index.",
            "format": "uint",
            "minimum": 0,
            "nullable": true,
            "type": "integer"
          },
          "nozzle_diameter": {
            "description": "Diameter of the extrusion nozzle, in mm.",
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "filaments",
          "nozzle_diameter"
        ],
        "type": "object"
      },
      "Filament": {
        "description": "Information about the filament being used in a FDM printer.",
        "properties": {
          "color": {
            "description": "The color (as hex without the `#`) of the filament, this is likely specific to the manufacturer.",
            "maxLength": 6,
            "minLength": 6,
            "nullable": true,
            "type": "string"
          },
          "material": {
            "allOf": [
              {
                "$ref": "#/components/schemas/FilamentMaterial"
              }
            ],
            "description": "The material that the filament is made of."
          },
          "name": {
            "description": "The name of the filament, this is likely specfic to the manufacturer.",
            "nullable": true,
            "type": "string"
          }
        },
        "required": [
          "material"
        ],
        "type": "object"
      },
      "FilamentMaterial": {
        "description": "The material that the filament is made of.",
        "oneOf": [
          {
            "description": "Polylactic acid based plastics",
            "properties": {
              "type": {
                "enum": [
                  "pla"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "Pla support",
            "properties": {
              "type": {
                "enum": [
                  "pla_support"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "acrylonitrile butadiene styrene based plastics",
            "properties": {
              "type": {
                "enum": [
                  "abs"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "polyethylene terephthalate glycol based plastics",
            "properties": {
              "type": {
                "enum": [
                  "petg"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "unsuprisingly, nylon based",
            "properties": {
              "type": {
                "enum": [
                  "nylon"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "thermoplastic polyurethane based urethane material",
            "properties": {
              "type": {
                "enum": [
                  "tpu"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "polyvinyl alcohol based material",
            "properties": {
              "type": {
                "enum": [
                  "pva"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "high impact polystyrene based material",
            "properties": {
              "type": {
                "enum": [
                  "hips"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "composite material with stuff in other stuff, something like PLA mixed with carbon fiber, kevlar, or fiberglass",
            "properties": {
              "type": {
                "enum": [
                  "composite"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "Unknown material",
            "properties": {
              "type": {
                "enum": [
                  "unknown"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          }
        ]
      },
      "HardwareConfiguration": {
        "description": "The hardware configuration of a machine.",
        "oneOf": [
          {
            "description": "No configuration is possible. This isn't the same conceptually as an `Option<HardwareConfiguration>`, because this indicates we positively know there is no possible configuration changes that are possible with this method of manufcture.",
            "properties": {
              "type": {
                "enum": [
                  "none"
                ],
                "type": "string"
              }
            },
            "required": [
              "type"
            ],
            "type": "object"
          },
          {
            "description": "Hardware configuration specific to FDM based printers",
            "properties": {
              "config": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/FdmHardwareConfiguration"
                  }
                ],
                "description": "The configuration for the FDM printer."
              },
              "type": {
                "enum": [
                  "fdm"
                ],
                "type": "string"
              }
            },
            "required": [
              "config",
              "type"
            ],
            "type": "object"
          }
        ]
      },
      "MachineInfoResponse": {
        "description": "Information regarding a connected machine.",
        "properties": {
          "extra": {
            "allOf": [
              {
                "$ref": "#/components/schemas/ExtraMachineInfoResponse"
              }
            ],
            "description": "Additional, per-machine information which is specific to the underlying machine type.",
            "nullable": true
          },
          "hardware_configuration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/HardwareConfiguration"
              }
            ],
            "description": "Information about how the Machine is currently configured."
          },
          "id": {
            "description": "Machine Identifier (ID) for the specific Machine.",
            "type": "string"
          },
          "machine_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MachineType"
              }
            ],
            "description": "Information regarding the method of manufacture."
          },
          "make_model": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MachineMakeModel"
              }
            ],
            "description": "Information regarding the make and model of the attached Machine."
          },
          "max_part_volume": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Volume"
              }
            ],
            "description": "Maximum part size that can be manufactured by this device. This may be some sort of theoretical upper bound, getting close to this limit seems like maybe a bad idea.\n\nThis may be `None` if the maximum size is not knowable by the Machine API.\n\nWhat \"close\" means is up to you!",
            "nullable": true
          },
          "progress": {
            "description": "Progress of the current print, if printing.",
            "format": "double",
            "nullable": true,
            "type": "number"
          },
          "state": {
            "allOf": [
              {
                "$ref": "#/components/schemas/MachineState"
              }
            ],
            "description": "Status of the printer -- be it printing, idle, or unreachable. This may dictate if a machine is capable of taking a new job."
          }
        },
        "required": [
          "hardware_configuration",
          "id",
          "machine_type",
          "make_model",
          "state"
        ],
        "type": "object"
      },
      "MachineMakeModel": {
        "description": "Information regarding the make/model of a discovered endpoint.",
        "properties": {
          "manufacturer": {
            "description": "The manufacturer that built the connected Machine.",
            "nullable": true,
            "type": "string"
          },
          "model": {
            "description": "The model of the connected Machine.",
            "nullable": true,
            "type": "string"
          },
          "serial": {
            "description": "The unique serial number of the connected Machine.",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "MachineState": {
        "description": "Current state of the machine -- be it printing, idle or offline. This can be used to determine if a printer is in the correct state to take a new job.",
        "oneOf": [
          {
            "description": "If a print state can not be resolved at this time, an Unknown may be returned.",
            "properties": {
              "state": {
                "enum": [
                  "unknown"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          },
          {
            "description": "Idle, and ready for another job.",
            "properties": {
              "state": {
                "enum": [
                  "idle"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          },
          {
            "description": "Running a job -- 3D printing or CNC-ing a part.",
            "properties": {
              "state": {
                "enum": [
                  "running"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          },
          {
            "description": "Machine is currently offline or unreachable.",
            "properties": {
              "state": {
                "enum": [
                  "offline"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          },
          {
            "description": "Job is underway but halted, waiting for some action to take place.",
            "properties": {
              "state": {
                "enum": [
                  "paused"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          },
          {
            "description": "Job is finished, but waiting manual action to move back to Idle.",
            "properties": {
              "state": {
                "enum": [
                  "complete"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          },
          {
            "description": "The printer has failed and is in an unknown state that may require manual attention to resolve. The inner value is a human readable description of what specifically has failed.",
            "properties": {
              "message": {
                "description": "A human-readable message describing the failure.",
                "nullable": true,
                "type": "string"
              },
              "state": {
                "enum": [
                  "failed"
                ],
                "type": "string"
              }
            },
            "required": [
              "state"
            ],
            "type": "object"
          }
        ]
      },
      "MachineType": {
        "description": "Specific technique by which this Machine takes a design, and produces a real-world 3D object.",
        "oneOf": [
          {
            "description": "Use light to cure a resin to build up layers.",
            "enum": [
              "stereolithography"
            ],
            "type": "string"
          },
          {
            "description": "Fused Deposition Modeling, layers of melted plastic.",
            "enum": [
              "fused_deposition"
            ],
            "type": "string"
          },
          {
            "description": "\"Computer numerical control\" - machine that grinds away material from a hunk of material to construct a part.",
            "enum": [
              "cnc"
            ],
            "type": "string"
          }
        ]
      },
      "NozzleDiameter": {
        "description": "A nozzle diameter.",
        "oneOf": [
          {
            "description": "0.2mm.",
            "enum": [
              "0.2"
            ],
            "type": "string"
          },
          {
            "description": "0.4mm.",
            "enum": [
              "0.4"
            ],
            "type": "string"
          },
          {
            "description": "0.6mm.",
            "enum": [
              "0.6"
            ],
            "type": "string"
          },
          {
            "description": "0.8mm.",
            "enum": [
              "0.8"
            ],
            "type": "string"
          }
        ]
      },
      "Pong": {
        "description": "The response from the `/ping` endpoint.",
        "properties": {
          "message": {
            "description": "The pong response.",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "type": "object"
      },
      "PrintJobResponse": {
        "description": "The response from the `/print` endpoint.",
        "properties": {
          "job_id": {
            "description": "The job id used for this print.",
            "type": "string"
          },
          "parameters": {
            "allOf": [
              {
                "$ref": "#/components/schemas/PrintParameters"
              }
            ],
            "description": "The parameters used for this print."
          }
        },
        "required": [
          "job_id",
          "parameters"
        ],
        "type": "object"
      },
      "PrintParameters": {
        "description": "Parameters for printing.",
        "properties": {
          "job_name": {
            "description": "The name for the job.",
            "type": "string"
          },
          "machine_id": {
            "description": "The machine id to print to.",
            "type": "string"
          },
          "slicer_configuration": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SlicerConfiguration"
              }
            ],
            "description": "Requested design-specific slicer configurations.",
            "nullable": true
          }
        },
        "required": [
          "job_name",
          "machine_id"
        ],
        "type": "object"
      },
      "SlicerConfiguration": {
        "description": "The slicer configuration is a set of parameters that are passed to the slicer to control how the gcode is generated.",
        "properties": {
          "filament_idx": {
            "description": "The filament to use for the print.",
            "format": "uint",
            "minimum": 0,
            "nullable": true,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Stage": {
        "description": "The print stage. These come from: https://github.com/SoftFever/OrcaSlicer/blob/431978baf17961df90f0d01871b0ad1d839d7f5d/src/slic3r/GUI/DeviceManager.cpp#L78",
        "oneOf": [
          {
            "description": "Nothing.",
            "enum": [
              "nothing"
            ],
            "type": "string"
          },
          {
            "description": "Empty.",
            "enum": [
              "empty"
            ],
            "type": "string"
          },
          {
            "description": "Auto bed leveling.",
            "enum": [
              "auto_bed_leveling"
            ],
            "type": "string"
          },
          {
            "description": "Heatbed preheating.",
            "enum": [
              "heatbed_preheating"
            ],
            "type": "string"
          },
          {
            "description": "Sweeping XY mech mode.",
            "enum": [
              "sweeping_xy_mech_mode"
            ],
            "type": "string"
          },
          {
            "description": "Changing filament.",
            "enum": [
              "changing_filament"
            ],
            "type": "string"
          },
          {
            "description": "M400 pause.",
            "enum": [
              "m400_pause"
            ],
            "type": "string"
          },
          {
            "description": "Paused due to filament runout.",
            "enum": [
              "paused_due_to_filament_runout"
            ],
            "type": "string"
          },
          {
            "description": "Heating hotend.",
            "enum": [
              "heating_hotend"
            ],
            "type": "string"
          },
          {
            "description": "Calibrating extrusion.",
            "enum": [
              "calibrating_extrusion"
            ],
            "type": "string"
          },
          {
            "description": "Scanning bed surface.",
            "enum": [
              "scanning_bed_surface"
            ],
            "type": "string"
          },
          {
            "description": "Inspecting first layer.",
            "enum": [
              "inspecting_first_layer"
            ],
            "type": "string"
          },
          {
            "description": "Identifying build plate type.",
            "enum": [
              "identifying_build_plate_type"
            ],
            "type": "string"
          },
          {
            "description": "Calibrating micro lidar.",
            "enum": [
              "calibrating_micro_lidar"
            ],
            "type": "string"
          },
          {
            "description": "Homing toolhead.",
            "enum": [
              "homing_toolhead"
            ],
            "type": "string"
          },
          {
            "description": "Cleaning nozzle tip.",
            "enum": [
              "cleaning_nozzle_tip"
            ],
            "type": "string"
          },
          {
            "description": "Checking extruder temperature.",
            "enum": [
              "checking_extruder_temperature"
            ],
            "type": "string"
          },
          {
            "description": "Printing was paused by the user.",
            "enum": [
              "printing_was_paused_by_the_user"
            ],
            "type": "string"
          },
          {
            "description": "Pause of front cover falling.",
            "enum": [
              "pause_of_front_cover_falling"
            ],
            "type": "string"
          },
          {
            "description": "Calibrating micro lidar.",
            "enum": [
              "calibrating_micro_lidar2"
            ],
            "type": "string"
          },
          {
            "description": "Calibrating extrusion flow.",
            "enum": [
              "calibrating_extrusion_flow"
            ],
            "type": "string"
          },
          {
            "description": "Paused due to nozzle temperature malfunction.",
            "enum": [
              "paused_due_to_nozzle_temperature_malfunction"
            ],
            "type": "string"
          },
          {
            "description": "Paused due to heat bed temperature malfunction.",
            "enum": [
              "paused_due_to_heat_bed_temperature_malfunction"
            ],
            "type": "string"
          },
          {
            "description": "Filament unloading.",
            "enum": [
              "filament_unloading"
            ],
            "type": "string"
          },
          {
            "description": "Skip step pause.",
            "enum": [
              "skip_step_pause"
            ],
            "type": "string"
          },
          {
            "description": "Filament loading.",
            "enum": [
              "filament_loading"
            ],
            "type": "string"
          },
          {
            "description": "Motor noise calibration.",
            "enum": [
              "motor_noise_calibration"
            ],
            "type": "string"
          },
          {
            "description": "Paused due to AMS lost.",
            "enum": [
              "paused_due_to_ams_lost"
            ],
            "type": "string"
          },
          {
            "description": "Paused due to low speed of the heat break fan.",
            "enum": [
              "paused_due_to_low_speed_of_the_heat_break_fan"
            ],
            "type": "string"
          },
          {
            "description": "Paused due to chamber temperature control error.",
            "enum": [
              "paused_due_to_chamber_temperature_control_error"
            ],
            "type": "string"
          },
          {
            "description": "Cooling chamber.",
            "enum": [
              "cooling_chamber"
            ],
            "type": "string"
          },
          {
            "description": "Paused by the Gcode inserted by the user.",
            "enum": [
              "paused_by_the_gcode_inserted_by_the_user"
            ],
            "type": "string"
          },
          {
            "description": "Motor noise showoff.",
            "enum": [
              "motor_noise_showoff"
            ],
            "type": "string"
          },
          {
            "description": "Nozzle filament covered detected pause.",
            "enum": [
              "nozzle_filament_covered_detected_pause"
            ],
            "type": "string"
          },
          {
            "description": "Cutter error pause.",
            "enum": [
              "cutter_error_pause"
            ],
            "type": "string"
          },
          {
            "description": "First layer error pause.",
            "enum": [
              "first_layer_error_pause"
            ],
            "type": "string"
          },
          {
            "description": "Nozzle clog pause.",
            "enum": [
              "nozzle_clog_pause"
            ],
            "type": "string"
          }
        ]
      },
      "Volume": {
        "description": "Set of three values to represent the extent of a 3-D Volume. This contains the width, depth, and height values, generally used to represent some maximum or minimum.\n\nAll measurements are in millimeters.",
        "properties": {
          "depth": {
            "description": "Depth of the volume (\"front to back\"), in millimeters.",
            "format": "double",
            "type": "number"
          },
          "height": {
            "description": "Height of the volume (\"up and down\"), in millimeters.",
            "format": "double",
            "type": "number"
          },
          "width": {
            "description": "Width of the volume (\"left and right\"), in millimeters.",
            "format": "double",
            "type": "number"
          }
        },
        "required": [
          "depth",
          "height",
          "width"
        ],
        "type": "object"
      }
    }
  },
  "info": {
    "contact": {
      "email": "machine-api@zoo.dev",
      "url": "https://zoo.dev"
    },
    "description": "",
    "title": "machine-api",
    "version": "0.1.1"
  },
  "openapi": "3.0.3",
  "paths": {
    "/": {
      "get": {
        "operationId": "api_get_schema",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Return the OpenAPI schema in JSON format.",
        "tags": [
          "meta"
        ]
      }
    },
    "/machines": {
      "get": {
        "operationId": "get_machines",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/MachineInfoResponse"
                  },
                  "title": "Array_of_MachineInfoResponse",
                  "type": "array"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "List available machines and their statuses",
        "tags": [
          "machines"
        ]
      }
    },
    "/machines/{id}": {
      "get": {
        "operationId": "get_machine",
        "parameters": [
          {
            "description": "The machine ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MachineInfoResponse"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Get the status of a specific machine",
        "tags": [
          "machines"
        ]
      }
    },
    "/metrics": {
      "get": {
        "operationId": "get_metrics",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "title": "String",
                  "type": "string"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "List available machines and their statuses",
        "tags": [
          "hidden"
        ]
      }
    },
    "/ping": {
      "get": {
        "operationId": "ping",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pong"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Return pong.",
        "tags": [
          "meta"
        ]
      }
    },
    "/print": {
      "post": {
        "operationId": "print_file",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "format": "binary",
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrintJobResponse"
                }
              }
            },
            "description": "successful operation"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "Print a given file. File must be a sliceable 3D model.",
        "tags": [
          "machines"
        ]
      }
    }
  },
  "tags": [
    {
      "description": "Hidden API endpoints that should not show up in the docs.",
      "externalDocs": {
        "url": "https://docs.zoo.dev/api/machines"
      },
      "name": "hidden"
    },
    {
      "description": "Utilities for making parts and discovering machines.",
      "externalDocs": {
        "url": "https://docs.zoo.dev/api/machines"
      },
      "name": "machines"
    },
    {
      "description": "Meta information about the API.",
      "externalDocs": {
        "url": "https://docs.zoo.dev/api/meta"
      },
      "name": "meta"
    }
  ]
}