Formlabs Developers
Download PreForm Insider to start developing with the PreForm API.
Version v1.0.0-alpha (latest)

Print Settings

The catalog of machine/material/layer-thickness/print-setting combinations Formlabs ships settings for, and validation of a candidate combination against that catalog.

List print settings#

POST/v1/print-setting/list/

List every machine/material/layer-thickness/print-setting combination Formlabs ships settings for, grouped by printer type and material.

Each material setting's scene_settings is the same shape accepted by /v1/print-setting/validate/, so a value from this list can be posted there directly to double-check it.

Pass compatible_with in the request body to restrict the response to a single connected printer's type instead of the full catalog. Omitting it, or sending no body at all, lists the full catalog.

Error codes#

HTTPerror.codeCause
400JSON_PARSE_ERRORThe request body is not a valid JSON object.
400JSON_SCHEMA_MATCH_ERRORThe body has an unknown field, or compatible_with isn't a string.
404NOT_FOUNDcompatible_with was given but no connected printer has that serial name.
500INTERNAL_ERRORServer misconfiguration: a printer type PreForm ships settings for is not registered. Not triggerable by request input.

Request bodyPrintSettingListRequest

  • compatible_withstring

    A connected printer's serial name.

ReturnsPrintSettingsListResponse

  • printer_typesarray of PrinterTypesRequired

    Every printer type PreForm ships print settings for, or the single matching connected printer's type if compatible_with was given.

    Show child attributes
    • labelstringRequired

      Display name, e.g. "Form 4".

    • supported_machine_type_idsarray of stringsRequired

      Canonical machine type ids this entry covers.

    • supported_product_namesarray of stringsRequired

      Marketing product names this entry covers.

    • build_volume_dimensions_mmarray of numbersRequired

      Build volume dimensions in millimeters, as [x, y, z].

      Exactly 3 items.

    • materialsarray of PrintMaterialsRequired
      Show child attributes
      • labelstringRequired

        Display name, e.g. "Black V5".

      • descriptionstringRequired

        Short marketing description of the material. May be empty.

      • material_settingsarray of MaterialSettingsRequired

        Every layer-thickness/print-setting variant of this material.

        Show child attributes
        • labelstringRequired

          Display label, e.g. "0.025 mm (Default settings)".

        • scene_settingsSceneSettingsRequired

          Identifies one machine/material/print-setting/layer-thickness combination, as returned by /v1/print-setting/list/. The same field names are used by /v1/print-setting/validate/.

          Show child attributes
          • machine_typestringRequired

            Canonical machine type id, e.g. "FORM-4-0".

          • material_codestringRequired

            Versioned material code, e.g. "FLGPBK05".

          • print_settingstringRequired

            Print setting profile code, e.g. "DEFAULT".

          • layer_thickness_mmnumber or stringRequired

            A layer thickness in millimeters, or the literal string "ADAPTIVE" for adaptive layer thickness. A numeric value formatted as a string (e.g. "0.025") is also accepted on input.

The catalog of supported combinations, or (if compatible_with matched) the single connected printer's type.

POST/v1/print-setting/list/
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.list_print_settings()
Terminal
curl -X POST "http://localhost:44388/v1/print-setting/list/" \
  -H "Content-Type: application/json" \
  -d '{}'
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.list_print_settings(
        compatible_with="SN123456",
    )
Terminal
curl -X POST "http://localhost:44388/v1/print-setting/list/" \
  -H "Content-Type: application/json" \
  -d '{
    "compatible_with": "SN123456"
  }'
Response
JSON
{
  "printer_types": [
    {
      "label": "Form 4",
      "supported_machine_type_ids": [
        "FORM-4-0"
      ],
      "supported_product_names": [
        "Form 4"
      ],
      "build_volume_dimensions_mm": [
        200,
        125,
        210
      ],
      "materials": [
        {
          "label": "Black V5",
          "description": "Fine detail, matte black finish",
          "material_settings": [
            {
              "label": "0.025 mm (Default settings)",
              "scene_settings": {
                "machine_type": "FORM-4-0",
                "material_code": "FLGPBK05",
                "print_setting": "DEFAULT",
                "layer_thickness_mm": 0.025
              }
            }
          ]
        }
      ]
    },
    {
      "label": "Fuse 1",
      "supported_machine_type_ids": [
        "PILK-1-0"
      ],
      "supported_product_names": [
        "Fuse 1"
      ],
      "build_volume_dimensions_mm": [
        165,
        165,
        300
      ],
      "materials": [
        {
          "label": "Nylon 11 V1",
          "description": "Strong, ductile material with high impact-resistance",
          "material_settings": [
            {
              "label": "0.110 mm (Default settings)",
              "scene_settings": {
                "machine_type": "PILK-1-0",
                "material_code": "FLP11B01",
                "print_setting": "DEFAULT",
                "layer_thickness_mm": 0.11
              }
            }
          ]
        }
      ]
    },
    {
      "label": "Fuse X1",
      "supported_machine_type_ids": [
        "FUSX-1-0",
        "FUSL-2-0"
      ],
      "supported_product_names": [
        "Fuse X1"
      ],
      "build_volume_dimensions_mm": [
        330,
        330,
        565
      ],
      "materials": [
        {
          "label": "Nylon 12 V1",
          "description": "Strong, durable material with high environmental stability",
          "material_settings": [
            {
              "label": "0.110 mm (Default settings)",
              "scene_settings": {
                "machine_type": "FUSX-1-0",
                "material_code": "FLP12G01",
                "print_setting": "DEFAULT",
                "layer_thickness_mm": 0.11
              }
            }
          ]
        }
      ]
    }
  ]
}
JSON
{
  "printer_types": [
    {
      "label": "Fuse 1+",
      "supported_machine_type_ids": [
        "FS30-1-0"
      ],
      "supported_product_names": [
        "Fuse 1+"
      ],
      "build_volume_dimensions_mm": [
        165,
        165,
        300
      ],
      "materials": [
        {
          "label": "Polypropylene V1",
          "description": "Ductile, lightweight, and chemically resistant",
          "material_settings": [
            {
              "label": "0.110 mm (Default settings)",
              "scene_settings": {
                "machine_type": "FS30-1-0",
                "material_code": "FLPLPG01",
                "print_setting": "DEFAULT",
                "layer_thickness_mm": 0.11
              }
            }
          ]
        }
      ]
    }
  ]
}

Validate a print setting combination#

POST/v1/print-setting/validate/

Check whether a machine_type/material_code/print_setting/layer_thickness_mm combination is one Formlabs ships, without creating a scene.

At least 3 of the 4 fields must be given. If exactly one is omitted, the response's options reports the valid values for that field given the other three. Omitting two or more is rejected, since each field's options are collected independently and nothing guarantees that combining one value from each list yields an actual valid combination.

A well-formed but unrecognized machine_type, material_code, print_setting, or layer_thickness_mm produces a normal 200 response with "valid": false.

Error codes#

HTTPerror.codeCause
400JSON_PARSE_ERRORThe request body is not a valid JSON object.
400JSON_SCHEMA_MATCH_ERRORThe body doesn't match the request schema: fewer than 3 of the 4 fields present, an unknown field, a field with the wrong type, or layer_thickness_mm not a number/"ADAPTIVE"/numeric string.
400INPUT_ERRORmachine_type was given but is (or canonicalizes to) the reserved UNKN-0-0 id. Not the same as an unrecognized machine type string, which yields valid: false.

Request bodyPrintSettingValidateRequest

  • machine_typestring

    Canonical machine type id, e.g. "FORM-4-0".

  • material_codestring

    Versioned material code, e.g. "FLGPBK05".

  • print_settingstring

    Print setting profile code, e.g. "DEFAULT".

  • layer_thickness_mmnumber or string

    A layer thickness in millimeters, or the literal string "ADAPTIVE" for adaptive layer thickness. A numeric value formatted as a string (e.g. "0.025") is also accepted on input.

ReturnsPrintSettingValidateResponse

  • validbooleanRequired

    Whether at least one shipped print setting matches the fields given.

  • optionsPrintSettingValidateOptions

    Valid values for the one field omitted from the request, given the other three. Exactly one of these four properties is present.

    Show child attributes
    • machine_typesarray of strings
    • material_codesarray of strings
    • print_settingsarray of strings
    • layer_thicknesses_mmarray of number or strings

The combination was checked.

POST/v1/print-setting/validate/
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.validate_print_setting(
        machine_type="FORM-4-0",
        material_code="FLGPBK05",
        print_setting="DEFAULT",
        layer_thickness_mm=0.025,
    )
Terminal
curl -X POST "http://localhost:44388/v1/print-setting/validate/" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_type": "FORM-4-0",
    "material_code": "FLGPBK05",
    "print_setting": "DEFAULT",
    "layer_thickness_mm": 0.025
  }'
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.validate_print_setting(
        machine_type="FORM-4-0",
        material_code="FLGPBK05",
        print_setting="DEFAULT",
        layer_thickness_mm=0.999,
    )
Terminal
curl -X POST "http://localhost:44388/v1/print-setting/validate/" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_type": "FORM-4-0",
    "material_code": "FLGPBK05",
    "print_setting": "DEFAULT",
    "layer_thickness_mm": 0.999
  }'
Python
from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    result = preform.validate_print_setting(
        machine_type="FORM-4-0",
        material_code="FLGPBK05",
        layer_thickness_mm=0.025,
    )
Terminal
curl -X POST "http://localhost:44388/v1/print-setting/validate/" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_type": "FORM-4-0",
    "material_code": "FLGPBK05",
    "layer_thickness_mm": 0.025
  }'
Response
JSON
{
  "valid": true
}
JSON
{
  "valid": false
}
JSON
{
  "valid": true,
  "options": {
    "print_settings": [
      "DEFAULT"
    ]
  }
}

Save a scene's print setting to a .fps file#

POST/v1/print-setting/save/

Exports the scene's current machine/material/print-setting/ layer-thickness combination, including any manual field overrides made in that scene, to a reusable .fps print settings file.

The saved file can later be applied to another scene via the fps_file field of /v1/scene/create/ or /v1/scene/update/.

Error codes#

HTTPerror.codeCause
400JSON_PARSE_ERRORThe request body is not a valid JSON object.
400JSON_SCHEMA_MATCH_ERRORscene_id or file is missing, file is empty or not a string, or an unrecognized field is present.
400INPUT_ERRORscene_id is not a well-formed UUID, or no scene with that id exists.
400OPERATION_FAILEDfile's extension is not .fps, or the file could not be written. The message carries the underlying reason.

Request bodyobject

  • scene_idstring (uuid)Required

    The id of the scene whose print setting to save.

  • filestringRequired

    Path to write the .fps file to.

    At least 1 characters.

Returnsno body

    The .fps file was saved. The response has no body.

    POST/v1/print-setting/save/
    Python
    from formlabs_sdk import FormlabsClient

with FormlabsClient() as client:
    preform = client.preform.connect()
    preform.save_print_setting(
        scene_id="3fa85f64-5717-4562-b3fc-2c963f66afa6",
        file="C:\\Users\\user\\Desktop\\custom.fps",
    )
    Terminal
    curl -X POST "http://localhost:44388/v1/print-setting/save/" \
  -H "Content-Type: application/json" \
  -d '{
    "scene_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "file": "C:\\Users\\user\\Desktop\\custom.fps"
  }'
    Response
    No response body.
    Feedback & Bug Reports