Formlabs Local API (0.9.9)

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.

Starting PreFormServer

The PreFormServer application can started manually from your Operating System's command prompt or terminal, but most integrations will start the application programmatically from integration code. The command line argument --port is required to specify the port number the HTTP Server will listen on.

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 --port 44388

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 scenes. By default, it caches 100 scenes in memory, with unlimited scenes stored on disk, though this may be changed with the --scene-cache-size parameter. Scenes are identified by their IDs, returned from the /scene/ endpoint. /scene/ endpoints also accept a scene ID of "default", which will use a single global scene. Endpoints with no scene id provided (e.g. /scene/auto-layout/) are deprecated. They will use the most recently created scene, and possibly modify it. All other /scene/ requests will use the user specified 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 endpoint 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.

Some long-running operations can be called asynchronously by adding ?async=true to the request. These requests will return immediately and the operation will be tracked separately. The caller can poll for completion using the /operations/{operation_id}/ endpoint, and track the percentage progress of the outstanding operation.

Requests involving the scene will always use the scene state at the time the request was made, without any partially completed operations. 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.

Multiple requests editing the same scene should NOT be made in parallel. If an "auto layout" request is made during an "auto support" request that has not finished, whichever operation finishes last will "win": either an auto-layout of unsupported models or the original layout with supports. PreformServer currently gives no warning when this happens.

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).

Endpoints related to Formlabs devices

Endpoints related to modifying the scene