Version v1.0.0-alpha (latest)

v1.0.0-alpha (latest)PreForm 3.64.0.661

Devices

Enumerate printers and Fleet Control printer groups PreForm knows about, discover new ones on the network, and upload firmware to them. Discovering Dashboard-registered printers and Fleet Control queues requires a Dashboard login (/v1/login/).

List known devices#

GET/v1/device/list/

Lists devices PreFormServer currently knows about: printers discovered on the local network, plus (if logged in via /v1/login/) Fleet Control printer groups and Dashboard- registered printers. Disconnected devices are not included.

Pass devices in the request body to look up specific devices by id instead of listing every connected device. When devices is given, can_print is ignored, and the ids are checked in order: the first one that doesn't match a connected device fails the whole request with no devices returned.

Error codes#

HTTP	`error.code`	Cause
400	`INVALID_QUERY_PARAMETER`	`can_print` is present but not `true` or `false`.
404	`NOT_FOUND`	An id in `devices` does not match any known device, or matches a device that is not currently connected.

Query parameters

can_printboolean
When true, only devices that can currently receive print jobs are returned (this excludes Fleet Control printer groups). Ignored when devices is given in the request body.
Defaults to false

Request bodyListDevicesRequest

devicesarray of strings
Device ids to look up, as returned in each device's id. Every id must belong to a currently connected device, or the whole request fails. See the endpoint's Error codes table.

Returnsobject

countintegerRequired
Number of devices in the response.
devicesarray of GenericDevice or FleetControlPrinterGroup or Form4FamilyDevice or Form3FamilyDevice or Fuse1Device or Form2DevicesRequired
Show child attributes
- Generic Deviceoption 1 of 6
  A device with no more specific status information available.
  Show fields
  - idstringRequired
    The device's serial name or other stable identifier.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstring
    Present only when connected directly over the local network.
  - firmware_versionstringRequired
  - ready_to_print_nowboolean
    If newly uploaded jobs print automatically instead of being queued. Present only for devices that can receive prints.
- Fleet Control Printer Groupoption 2 of 6
  A Fleet Control queue: a group of one or more printers managed together through a Formlabs Dashboard queue.
  Show fields
  - idstringRequired
    The group's stable identifier.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - firmware_versionstringRequired
    Always empty, since a printer group has no single firmware version.
  - dashboard_group_idstring (uuid)Required
    Id of the group on Formlabs Dashboard.
  - dashboard_queue_idstring (uuid)Required
    Id of the Fleet Control queue on Formlabs Dashboard.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
  - queue_pausedbooleanRequired
    If the queue is currently paused.
  - has_form_autobooleanRequired
    If the group includes a Form Auto.
  - supported_machine_type_idsarray of stringsRequired
  - printersarray of objectsRequired
    The individual printers currently in this group.
    Show child attributes
    idstringRequired
    The printer's serial name.
    machine_type_idstringRequired
    Canonical machine type id, e.g. "FORM-4-0".
- Form 4 or Form 4L Printeroption 3 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - is_remote_print_enabledbooleanRequired
    If the printer can be started remotely via Formlabs Dashboard.
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - tank_idstringRequired
  - tank_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cartridge_dataCartridgeDataRequired
    Cartridge data keyed by cartridge id. Unlike every other v1 response field, the keys inside each entry are camelCase, not snake_case: this object is a verbatim passthrough of the printer's internal cartridge tracking data.
    Show child attributes
    cartridgeMaterialCodestringRequired
    Versioned material code, e.g. "FLGPBK05".
    cartridgeEstimatedVolumeDispensed_mLnumberRequired
    Estimated volume of material dispensed from this cartridge so far, in mL.
    cartridgeOriginalVolume_mLnumberRequired
    The cartridge's original, unused volume, in mL.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
- Form 3 or Form 3L Printeroption 4 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - is_remote_print_enabledbooleanRequired
    If the printer can be started remotely via Formlabs Dashboard.
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - tank_idstringRequired
  - tank_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cartridge_dataCartridgeDataRequired
    Cartridge data keyed by cartridge id. Unlike every other v1 response field, the keys inside each entry are camelCase, not snake_case: this object is a verbatim passthrough of the printer's internal cartridge tracking data.
    Show child attributes
    cartridgeMaterialCodestringRequired
    Versioned material code, e.g. "FLGPBK05".
    cartridgeEstimatedVolumeDispensed_mLnumberRequired
    Estimated volume of material dispensed from this cartridge so far, in mL.
    cartridgeOriginalVolume_mLnumberRequired
    The cartridge's original, unused volume, in mL.
  - form_auto_statusstringRequired
    Human-readable Form Auto status message. Not machine-readable. Never match on its value.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
- Fuse 1/1+ Printeroption 5 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - is_remote_print_enabledbooleanRequired
    If the printer can be started remotely via Formlabs Dashboard.
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - bed_temperature_cnumberRequired
  - powder_levelstringRequired
    Human-readable powder level message. Not machine-readable. Never match on its value.
  - printing_layerintegerRequired
    Index of the layer currently printing, if any.
  - printing_guidstringRequired
    Id of the print job currently loaded, if any.
  - cylinder_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cylinder_serialstringRequired
  - printer_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - powder_credit_gnumberRequired
    Remaining powder credit, in grams.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
- Form 2 Printeroption 6 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - tank_idstringRequired
  - tank_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cartridge_dataCartridgeDataRequired
    Cartridge data keyed by cartridge id. Unlike every other v1 response field, the keys inside each entry are camelCase, not snake_case: this object is a verbatim passthrough of the printer's internal cartridge tracking data.
    Show child attributes
    cartridgeMaterialCodestringRequired
    Versioned material code, e.g. "FLGPBK05".
    cartridgeEstimatedVolumeDispensed_mLnumberRequired
    Estimated volume of material dispensed from this cartridge so far, in mL.
    cartridgeOriginalVolume_mLnumberRequired
    The cartridge's original, unused volume, in mL.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.

The connected devices matching the request, or every connected device if devices was omitted.

GET/v1/device/list/

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.list_devices()

Terminal

curl "http://localhost:44388/v1/device/list/" \
  -H "Content-Type: application/json" \
  -d '{}'

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.list_devices(
        devices=["ArtfulChameleon", "InconsequentialSnail"],
    )

Terminal

curl "http://localhost:44388/v1/device/list/" \
  -H "Content-Type: application/json" \
  -d '{
    "devices": [
      "ArtfulChameleon",
      "InconsequentialSnail"
    ]
  }'

Response

JSON

{
  "count": 2,
  "devices": [
    {
      "id": "ArtfulChameleon",
      "product_name": "Form 4",
      "status": "Idle",
      "is_connected": true,
      "connection_type": "WIFI",
      "ip_address": "192.168.1.42",
      "firmware_version": "1.9.0-2444",
      "is_remote_print_enabled": true,
      "estimated_print_time_remaining_ms": 0,
      "tank_id": "T1234567",
      "tank_material_code": "FLGPCL05",
      "cartridge_data": {},
      "ready_to_print_now": true
    },
    {
      "id": "InconsequentialSnail",
      "product_name": "Printer Group",
      "status": "Idle",
      "is_connected": true,
      "connection_type": "REMOTE",
      "firmware_version": "",
      "dashboard_group_id": "0f86346f-ac2c-47c1-a9e7-4888452f4fcf",
      "dashboard_queue_id": "71b46642-b2b7-4683-a534-ebd4b4ad3efe",
      "ready_to_print_now": false,
      "queue_paused": false,
      "has_form_auto": false,
      "supported_machine_type_ids": [
        "DGSR-1-0",
        "FORM-4-0",
        "FS30-1-0"
      ],
      "printers": [
        {
          "id": "CloudyPangolin",
          "machine_type_id": "DGSR-1-0"
        }
      ]
    }
  ]
}

Discover devices on the network#

POST/v1/device/discover/

Waits up to timeout_seconds for printers to announce themselves on the local network, then returns every connected, non-virtual device known afterwards. This is the same device set /v1/device/list/ would return at that point. Call this endpoint to give newly powered-on or newly networked printers a chance to appear before listing them.

Pass printer to target a specific device by its local network IP address, serial name (e.g. ArtfulChameleon), or a Fleet Control Queue id. These are the same address forms accepted by printer on /v1/scene/print/ and /v1/device/upload-firmware/. If that device is found but is virtual, it is excluded from the response, which then reports zero devices.

This can take up to timeout_seconds to respond, so prefer ?async=true and poll the returned operation.

Error codes#

HTTP	`error.code`	Cause
400	`INVALID_QUERY_PARAMETER`	`async` is present but not `true` or `false`.
400	`JSON_PARSE_ERROR`	The request body is not a valid JSON object.
400	`JSON_SCHEMA_MATCH_ERROR`	`timeout_seconds` is present but not a non-negative integer, `printer` is present but not a string, or an unrecognized field is present.
400	`OPERATION_FAILED`	`printer` was given but no matching device was found within `timeout_seconds`. The message carries the underlying reason.

Query parameters

asyncboolean
When true, returns 202 Accepted immediately with the operation's id and its operation_url to poll for the result, instead of blocking until the operation completes.
Defaults to false

Request bodyDiscoverDevicesRequest

timeout_secondsinteger
Number of seconds to wait for devices to be found.
At least 0.
Defaults to 60
printerstring
Address of a single device to wait for, instead of discovering broadly. Printer serial name, IP address, or Fleet Control Queue id.

Returns 200 OKobject

countintegerRequired
Number of devices in the response.
devicesarray of GenericDevice or FleetControlPrinterGroup or Form4FamilyDevice or Form3FamilyDevice or Fuse1Device or Form2DevicesRequired
Show child attributes
- Generic Deviceoption 1 of 6
  A device with no more specific status information available.
  Show fields
  - idstringRequired
    The device's serial name or other stable identifier.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstring
    Present only when connected directly over the local network.
  - firmware_versionstringRequired
  - ready_to_print_nowboolean
    If newly uploaded jobs print automatically instead of being queued. Present only for devices that can receive prints.
- Fleet Control Printer Groupoption 2 of 6
  A Fleet Control queue: a group of one or more printers managed together through a Formlabs Dashboard queue.
  Show fields
  - idstringRequired
    The group's stable identifier.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - firmware_versionstringRequired
    Always empty, since a printer group has no single firmware version.
  - dashboard_group_idstring (uuid)Required
    Id of the group on Formlabs Dashboard.
  - dashboard_queue_idstring (uuid)Required
    Id of the Fleet Control queue on Formlabs Dashboard.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
  - queue_pausedbooleanRequired
    If the queue is currently paused.
  - has_form_autobooleanRequired
    If the group includes a Form Auto.
  - supported_machine_type_idsarray of stringsRequired
  - printersarray of objectsRequired
    The individual printers currently in this group.
    Show child attributes
    idstringRequired
    The printer's serial name.
    machine_type_idstringRequired
    Canonical machine type id, e.g. "FORM-4-0".
- Form 4 or Form 4L Printeroption 3 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - is_remote_print_enabledbooleanRequired
    If the printer can be started remotely via Formlabs Dashboard.
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - tank_idstringRequired
  - tank_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cartridge_dataCartridgeDataRequired
    Cartridge data keyed by cartridge id. Unlike every other v1 response field, the keys inside each entry are camelCase, not snake_case: this object is a verbatim passthrough of the printer's internal cartridge tracking data.
    Show child attributes
    cartridgeMaterialCodestringRequired
    Versioned material code, e.g. "FLGPBK05".
    cartridgeEstimatedVolumeDispensed_mLnumberRequired
    Estimated volume of material dispensed from this cartridge so far, in mL.
    cartridgeOriginalVolume_mLnumberRequired
    The cartridge's original, unused volume, in mL.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
- Form 3 or Form 3L Printeroption 4 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - is_remote_print_enabledbooleanRequired
    If the printer can be started remotely via Formlabs Dashboard.
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - tank_idstringRequired
  - tank_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cartridge_dataCartridgeDataRequired
    Cartridge data keyed by cartridge id. Unlike every other v1 response field, the keys inside each entry are camelCase, not snake_case: this object is a verbatim passthrough of the printer's internal cartridge tracking data.
    Show child attributes
    cartridgeMaterialCodestringRequired
    Versioned material code, e.g. "FLGPBK05".
    cartridgeEstimatedVolumeDispensed_mLnumberRequired
    Estimated volume of material dispensed from this cartridge so far, in mL.
    cartridgeOriginalVolume_mLnumberRequired
    The cartridge's original, unused volume, in mL.
  - form_auto_statusstringRequired
    Human-readable Form Auto status message. Not machine-readable. Never match on its value.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
- Fuse 1/1+ Printeroption 5 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - is_remote_print_enabledbooleanRequired
    If the printer can be started remotely via Formlabs Dashboard.
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - bed_temperature_cnumberRequired
  - powder_levelstringRequired
    Human-readable powder level message. Not machine-readable. Never match on its value.
  - printing_layerintegerRequired
    Index of the layer currently printing, if any.
  - printing_guidstringRequired
    Id of the print job currently loaded, if any.
  - cylinder_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cylinder_serialstringRequired
  - printer_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - powder_credit_gnumberRequired
    Remaining powder credit, in grams.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.
- Form 2 Printeroption 6 of 6
  Show fields
  - idstringRequired
    The printer's serial name.
  - product_namestringRequired
  - statusstringRequired
    Human-readable status message. Not machine-readable. Never match on its value.
  - is_connectedbooleanRequired
  - connection_typeenum DeviceConnectionTypeRequired
    How a device is currently connected, if known.
    Currently one of the following; more may be added:
    UNKNOWN
    Connected locally, but the specific interface could not be determined.
    VIRTUAL
    A virtual/simulated device, not a real physical printer.
    REMOTE
    Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
    USB
    Connected directly over USB.
    WIFI
    Connected over the local Wi-Fi network.
    ETHERNET
    Connected over a wired Ethernet network.
    No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).
  - ip_addressstringRequired
  - firmware_versionstringRequired
  - estimated_print_time_remaining_msintegerRequired
    Milliseconds remaining in the current print, if any, and 0 otherwise.
  - tank_idstringRequired
  - tank_material_codestringRequired
    Versioned material code, e.g. "FLGPBK05".
  - cartridge_dataCartridgeDataRequired
    Cartridge data keyed by cartridge id. Unlike every other v1 response field, the keys inside each entry are camelCase, not snake_case: this object is a verbatim passthrough of the printer's internal cartridge tracking data.
    Show child attributes
    cartridgeMaterialCodestringRequired
    Versioned material code, e.g. "FLGPBK05".
    cartridgeEstimatedVolumeDispensed_mLnumberRequired
    Estimated volume of material dispensed from this cartridge so far, in mL.
    cartridgeOriginalVolume_mLnumberRequired
    The cartridge's original, unused volume, in mL.
  - ready_to_print_nowbooleanRequired
    If newly uploaded jobs print automatically instead of being queued.

The devices known after waiting for discovery to finish.

Returns 202 AcceptedOperationAccepted

operation_idstring (uuid)Required
Randomly generated id of the tracked operation.
operation_urlstringRequired
Server-relative URL of this operation's record: /v1/operation/get/?operation_id=<operation_id>. GET it to follow progress and retrieve the result.
messagestringRequired
Human-readable pointer to where the result will appear. Purely informational. Use operation_url programmatically.

The request was accepted for asynchronous processing (?async=true). Poll the operations endpoints with the returned id.

Response headers (202)

Locationstring
Server-relative URL of the accepted operation's record, identical to the response body's operation_url. GET it to follow progress and retrieve the result.

POST/v1/device/discover/

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.discover_devices(
        timeout_seconds=10,
    )

Terminal

curl -X POST "http://localhost:44388/v1/device/discover/" \
  -H "Content-Type: application/json" \
  -d '{
    "timeout_seconds": 10
  }'

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.discover_devices(
        printer="192.168.1.10",
        timeout_seconds=10,
    )

Terminal

curl -X POST "http://localhost:44388/v1/device/discover/" \
  -H "Content-Type: application/json" \
  -d '{
    "printer": "192.168.1.10",
    "timeout_seconds": 10
  }'

Response

JSON

{
  "count": 1,
  "devices": [
    {
      "id": "ArtfulChameleon",
      "product_name": "Form 4",
      "status": "Idle",
      "is_connected": true,
      "connection_type": "WIFI",
      "ip_address": "192.168.1.42",
      "firmware_version": "1.9.0-2444",
      "is_remote_print_enabled": true,
      "estimated_print_time_remaining_ms": 0,
      "tank_id": "T1234567",
      "tank_material_code": "FLGPCL05",
      "cartridge_data": {},
      "ready_to_print_now": true
    }
  ]
}

JSON

{
  "operation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "operation_url": "/v1/operation/get/?operation_id=7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message": "Operation accepted. Poll GET /v1/operation/get/?operation_id=7c9e6679-7425-40de-944b-e07fc1f90ae7 until 'status' is SUCCEEDED or FAILED; the endpoint's response will appear in the 'result' field there."
}

Upload firmware to a device#

POST/v1/device/upload-firmware/

Uploads a firmware file to printer and installs it. printer is a local network IP address, a printer serial name, or a Fleet Control Queue id. The request will time out after 60 seconds if the printer is not found.

The target must be a locally connected, non-remote printer that supports firmware updates. Printers connected only via Dashboard (Remote) are rejected.

This can take a while, especially finding the printer on the network, so prefer ?async=true and poll the returned operation.

Error codes#

HTTP	`error.code`	Cause
400	`INVALID_QUERY_PARAMETER`	`async` is present but not `true` or `false`.
400	`JSON_PARSE_ERROR`	The request body is not a valid JSON object.
400	`JSON_SCHEMA_MATCH_ERROR`	`printer` or `file_path` is missing or not a string, or an unrecognized field is present.
400	`OPERATION_FAILED`	The printer could not be found within 60 seconds, is offline, is connected only via Dashboard (Remote), does not support firmware updates, or the upload itself failed. The message carries the underlying reason.

Query parameters

asyncboolean
When true, returns 202 Accepted immediately with the operation's id and its operation_url to poll for the result, instead of blocking until the operation completes.
Defaults to false

Request bodyUploadFirmwareRequest

printerstringRequired
Printer serial name, IP address, or Fleet Control Queue id.
file_pathstringRequired
Path, on the machine running PreFormServer, to the firmware .formware or .formware2 file to upload.

Returns 200 OKno body

The firmware was uploaded and installed. The response has no body.

Returns 202 AcceptedOperationAccepted

operation_idstring (uuid)Required
Randomly generated id of the tracked operation.
operation_urlstringRequired
Server-relative URL of this operation's record: /v1/operation/get/?operation_id=<operation_id>. GET it to follow progress and retrieve the result.
messagestringRequired
Human-readable pointer to where the result will appear. Purely informational. Use operation_url programmatically.

The request was accepted for asynchronous processing (?async=true). Poll the operations endpoints with the returned id.

Response headers (202)

Locationstring
Server-relative URL of the accepted operation's record, identical to the response body's operation_url. GET it to follow progress and retrieve the result.

POST/v1/device/upload-firmware/

Python

from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    preform.upload_firmware(
        printer="Form4-TestyTest",
        file_path="C:\\Users\\user\\Desktop\\form4-public-1.9.0-2444.formware",
    )

Terminal

curl -X POST "http://localhost:44388/v1/device/upload-firmware/" \
  -H "Content-Type: application/json" \
  -d '{
    "printer": "Form4-TestyTest",
    "file_path": "C:\\Users\\user\\Desktop\\form4-public-1.9.0-2444.formware"
  }'

Response

No response body.

JSON

{
  "operation_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "operation_url": "/v1/operation/get/?operation_id=7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "message": "Operation accepted. Poll GET /v1/operation/get/?operation_id=7c9e6679-7425-40de-944b-e07fc1f90ae7 until 'status' is SUCCEEDED or FAILED; the endpoint's response will appear in the 'result' field there."
}

Schemas#

DeviceConnectionType#

enum DeviceConnectionType

How a device is currently connected, if known.

Currently one of the following; more may be added:

UNKNOWN: Connected locally, but the specific interface could not be determined.
VIRTUAL: A virtual/simulated device, not a real physical printer.
REMOTE: Connected via Formlabs Dashboard / Fleet Control, not directly on the local network.
USB: Connected directly over USB.
WIFI: Connected over the local Wi-Fi network.
ETHERNET: Connected over a wired Ethernet network.
: No direct local connection (e.g. a Fleet Control printer group, which has no connection of its own).