Formlabs Local API (0.8.0)

The Formlabs Local API is designed for integrations that want to automate job preparation, getting local-network printer status, or sending jobs to Formlabs printers without launching the PreForm graphical user interface. A server application must be installed and run on a user's computer to use this API.

Example use cases:

• Scripted job preparation that takes a folder of models, sets up a print, and uploads it to a printer without user input.
• Deep and custom integrations into 3D Modeling and Design software to prepare print scenes beyond the scope of the PreForm Command Line Arguments.

This API uses RESTful principles. This means the API is organized around resources and collections of resources. Resources and collections are each available at their own URI. You can interact with these resources using standard HTTP Methods on the resource's URI.

Example endpoint:

GET http://localhost:44388/scene/

Responses from the API server will be in JSON and are documented throughout the reference docs. This API is described by an OpenAPI Specification. This interactive documentation is automatically generated from the specification file.

All Local API integrations involve starting the PreFormServer background application to expose its HTTP API, then making local HTTP API calls in your own code. This application is like PreForm, Formlabs' regular job preparation application, but it does not open a graphical window, and interaction is done via HTTP API requests. The PreFormServer application is supported on Windows and MacOS with separate downloads for each Operating System.

Installing PreFormServer

The PreFormServer application can be downloaded from the Formlabs API downloads and release notes page. After downloading, unzip the file and move the application to the desired location on your computer. Any location can be used as the path to the application should be referenced from your integration code.

In the current release, we also recommend adding the PreFormServer application the users' antivirus software exception list or explicitly whitelisting the application in the security settings of MacOS.

On MacOS, you can use the following terminal command to whitelist the PreFormServer application:

xattr -r -d com.apple.quarantine PreFormServer.app

Starting PreFormServer

The PreFormServer application can started manually from your Operating System's command prompt or terminal, but most integrations will start the application programatically from integration code. By default the HTTP Server will listen on port 44388, but this can be changed by passing in a different port number as the command line argument --port to the PreFormServer application.

The HTTP API server started by the PreFormServer application cannot immediately respond to requests. When the server is ready to accept requests, it will output READY FOR INPUT in the standard output.

For example, running the PreFormServer application on Windows from the command prompt:

PreFormServer.exe

will output something like the following:

starting HTTP server
Listening...
HTTP server listening on port  44388
READY FOR INPUT

The code to make HTTP API requests to a running PreFormServer can be written directly in your integration code or by using a generated library that does the API calls. The endpoints and format of the HTTP API are described on this page and in the openapi.yaml file. Formlabs provides an example Python library that handles the setup and request formatting.

• Scene: The current state of a job that can be printed on a particular printer model. This includes both the “Scene Settings” and all of the currently loaded models and their support structures.
• Scene Settings: Printer type and material information of scene. Describes the build platform size, the printer capabilities, and what material and print settings it is set up to be printed with.

The PreForm Server is stateful in that while it is running, it keeps a cache of the current scene and requests will use the cached scene and possibly modify it. For example, initially a scene may be empty and then if a load model request is made then the cached scene will have one model loaded. Calling the load model requests again will load another copy of the model resulting in two models in the cached scene.

Unless otherwise stated, API calls are blocking: the HTTP request will not return until the operation has completed. Some requests like running the auto support action on a scene with many complicated models could take over 1 minute (depending on computer resources). The Server has a timeout of 10 minutes for all requests.

Requests made asynchronously will use the last cached state. For example, if a “get scene” request is made during a “auto support” request that has not finished, then the “get scene” request will return data that will not include the auto support changes.

When saving and loading files, the local API inputs expect full operating system paths to local files on disk.

Correct file path:

• C:\Projects\Models\part.stl

Incorrect file paths:

• .\Models\part.stl
• %ENV_VAR%\part.stl
• part.stl
• https://filestorage.com/part.stl

Conventional HTTP response codes are used to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Formlabs' servers.

The HTTP Server that PreForm uses to communicate is only exposed to the local network of your computer and not to the public Internet, unless you have configured your computer to expose the port running the PreForm Server to the Internet.

Some requests require an Internet connection, require Dashboard login, and make web requests to perform their action (such as printing to a remote printer).

Operations related to Formlabs devices

Operations related to modifying the scene

Operations related to getting information about a scene

Operations related to remote access and printing that require Internet access and authentication with Formlabs Web Services."

Operations related to getting available print settings.

Get information about the API itself