Formlabs Logo
API docs by Redocly

Formlabs Web API (0.8.1)

Download OpenAPI specification:Download

URL: https://support.formlabs.com/ Terms of Service

Introduction

The Formlabs Web API provides access to Formlabs’ remote control and remote monitoring features for Internet-connected Formlabs products registered to your Dashboard account.

Some example use cases of the Dashboard Developer API:

  1. Create automated custom reports on Printer usage, material usage, and job history to gain more insights into print production
  2. More efficiently manage Printers by integrating Printer status data into existing systems (ERP/MES/custom)

Terms and Conditions

  • Formlabs reserves the right to revoke or invalidate your API key at any time without warning.
  • As a beta, conditions of access to the API may change in the future, access may be bundled into other future software products, etc. (we will make an effort to provide as much warning as possible)
  • As a beta, the API may change at any time without warning in such a way that it may fail to support existing workflows (though we will make an effort to provide advanced notice where possible)
  • You agree not to exceed the Dashboard Developer API rate limit as detailed in the "Rate Limit" section below.
  • You will be given access to certain non-public information, software, and specifications that are confidential and proprietary to Formlabs. You will not share these outside your organization.
  • By participating in this Beta you may be sharing information with Formlabs. Any information shared is governed by our Privacy Policy https://formlabs.com/support/privacy-policy/
  • The Dashboard Developer API works with Formlabs Printers that are connected to the internet and registered to Dashboard. Printers registered to Dashboard share data with Formlabs (detailed in the Data Collection section of the Privacy Policy: https://formlabs.com/support/privacy-policy/#Data-Collection). For more information about how to set up Printers and register them to Dashboard, see this link: https://support.formlabs.com/s/article/Dashboard-Overview-and-Setup

Technical Overview

The Formlabs Dashboard Developer API is a REST HTTP API using JSON as the response data format.

Formlabs Dashboard Developer API is HTTP-based. Send a HTTP GET request to an endpoint to retrieve data from that endpoint. The integrating system should be able to make HTTP requests and process responses in JSON format.

Formlabs Dashboard Developer API uses the standard OAuth Authentication Flow, and all API endpoints require authentication. The access token created is valid for a day, so make sure to refresh the token regularly to maintain seamless integration with the Dashboard Developer API and ensure uninterrupted workflow.

Versioning

The Dashboard Developer API uses resource-based versioning, meaning API endpoints are versioned independently, rather than globally across all endpoints.

Formlabs may change the version of an endpoint to first keep in sync with product updates (could be an addition or a removal of data), in addition to any changes based on customer feedback to allow easier integrations.

Versioning can occur in the following situations:

  • The format of the response data is required to change
  • The format of the response type is required to change

Any outstanding version changes or upgrades occurred on endpoints will be highlighted and documented.

Rate Limit

The rate of requests to the Dashboard Developer API is limited to prevent the abuse of the system. Requests from the same IP address are limited to 100 requests/second. Requests from the same authenticated user are limited to 1500 requests/hour. After a rate limit is exceeded, requests will return a HTTP status code of 429 with a “Retry-after” header outlining when the next request can be made.

Account Setup & Printer Registration

The Dashboard Developer API is only available to Formlabs.com account-holding users that are registered and have active Formlabs 3D Printer(s) associated with their accounts. If you do not have a Formlabs.com account, or you have an account but don’t have your Printers connected to it, please follow the instructions below:

  1. Sign up for a Formlabs.com account at https://formlabs.com/dashboard/#register
  2. Register the Formlabs 3D Printers at https://formlabs.com/dashboard/#setup. This involves connecting a Formlabs 3D Printer to the Internet and then visiting the Dashboard Registration screen on the Printer to get a registration code. Type this registration code on the Dashboard Printer registration page to complete the registration.
  3. Now the Dashboard should show your Printer’s live status, show a history of prints, etc.
  4. Visit the Developer Tools page at, and create your Application credentials
  5. Once you have your Client ID and the Client Secret, go to the Authentication section for instructions on how to get an API access token and start using the Dashboard Developer API.

Authentication

Prerequisites

Make sure that you have the following prior to proceeding on with this section:

  • You have Formlabs Printer(s) connected to your Formlabs.com account
  • You have your Client ID and Client Secret Application credentials
    To get your Client ID and Client Secret, visit the Developer Tools page and create your Application credentials.

Getting an Access Token

To authenticate with the Dashboard Developer API, you need to get an access token. The access token is used to authenticate your requests to the API. See the Request an access token endpoint for more information.

Example:

curl --request POST \
--url https://api.formlabs.com/developer/v1/o/token/ \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>'

Using the Access Token

Once you have the access token, you can use it to authenticate your requests to the Dashboard Developer API. To authenticate your requests, you need to include the access token in the Authorization header of your request. The access token should be prefixed with the word “bearer” followed by a space.

Example:

curl --request GET \
--url https://api.formlabs.com/developer/v1/printers/ \
--header 'content-type: application/x-www-form-urlencoded' \
--header 'Authorization: bearer <access_token>'

Revoking an Access Token

If you need to revoke an access token, you can do so by using the Revoke an access token endpoint.

Request an access token

To log in to the Dashboard Developer API, you need to request an access token. This token is used to authenticate your requests to the API. You can request an access token by providing your client ID and client secret.

Request Body schema: application/x-www-form-urlencoded
grant_type
required
string

The type of grant being used. Currently only client_credentials is supported

client_id
required
string

Your Client ID.

client_secret
required
string

Your Client Secret.

Responses

Request samples

Content type
application/x-www-form-urlencoded
grant_type=client_secret&client_id=your_client_id&client_secret=your_client_secret

Response samples

Content type
application/json
{
  • "access_token": "your_access_token",
  • "token_type": "Bearer",
  • "expires_in": 86400,
  • "scope": "developer-api"
}

Revoke an access token

You can log out from your current authenticated session by revoking the access token. When successfully revoked, the API does not return any response. As aforementioned, once you send a request to revoke the specified access token, this token can no longer be used to make requests to the Dashboard Developer API. Please retrieve a new access token to start using the API again.

Request Body schema: application/x-www-form-urlencoded
token
required
string

Your access token.

client_id
required
string

Your client ID.

client_secret
required
string

Your client secret.

Responses

Request samples

Content type
application/x-www-form-urlencoded
token=your_access_token&client_id=your_client_id&client_secret=your_client_secret

Response samples

Content type
application/json
{
  • "error": "invalid_client"
}

Printers

This section contains endpoints for managing Printers.

printers_list

List of all Printers associated with my account

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

printers_retrieve

Specific Printer associated with my account

Authorizations:
bearerAuth
path Parameters
printer_serial
required
string

A unique value identifying this printer.

Responses

Response samples

Content type
application/json
{
  • "serial": "string",
  • "alias": "string",
  • "machine_type_id": "string",
  • "printer_status": {
    },
  • "cartridge_status": [
    ],
  • "tank_status": {
    },
  • "group": {
    },
  • "previous_print_run": {
    },
  • "firmware_version": "string",
  • "location": "string"
}

Prints

This section contains endpoints for listing and searching Prints.

prints_list

List of all prints associated with my account

Authorizations:
bearerAuth
query Parameters
date
string <date-time>

Filter by date time (ISO 8601 Format)

date__gt
string <date-time>

Filter by date time greater than date time specified (ISO 8601 Format)

date__lt
string <date-time>

Filter by date time less than date time specified (ISO 8601 Format)

machine_type_id
Array of strings

Filter by machine type id.

material
string
name
string

Filter by name of the print (Substring Match)

page
integer

A page number within the paginated result set.

per_page
integer

Number of results to return per page.

printer
string

Filter by printer serial

status
string

Filter by status of the print. Possible values are: * QUEUED - Queued * PREPRINT - Preprint * PRINTING - Printing * PAUSING - Pausing * PAUSED - Paused * FINISHED - Finished * ABORTING - Aborting * ABORTED - Aborted * ERROR - Error * WAITING_FOR_RESOLUTION - Waiting for Resolution * PREHEAT - Preheat * PRECOAT - Precoat * POSTCOAT - Postcoat

Responses

Response samples

Content type
application/json
{
  • "count": 123,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "results": [
    ]
}

printers_prints_list

List of all prints associated with my account

Authorizations:
bearerAuth
path Parameters
printer_serial
required
string
query Parameters
date
string <date-time>

Filter by date time (ISO 8601 Format)

date__gt
string <date-time>

Filter by date time greater than date time specified (ISO 8601 Format)

date__lt
string <date-time>

Filter by date time less than date time specified (ISO 8601 Format)

machine_type_id
Array of strings

Filter by machine type id.

material
string
name
string

Filter by name of the print (Substring Match)

page
integer

A page number within the paginated result set.

per_page
integer

Number of results to return per page.

printer
string

Filter by printer serial

status
string

Filter by status of the print. Possible values are: * QUEUED - Queued * PREPRINT - Preprint * PRINTING - Printing * PAUSING - Pausing * PAUSED - Paused * FINISHED - Finished * ABORTING - Aborting * ABORTED - Aborted * ERROR - Error * WAITING_FOR_RESOLUTION - Waiting for Resolution * PREHEAT - Preheat * PRECOAT - Precoat * POSTCOAT - Postcoat

Responses

Response samples

Content type
application/json
{
  • "count": 123,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "results": [
    ]
}

Tanks

This section contains endpoints for listing Tanks.

tanks_list

List of all resin tanks associated with my account

Authorizations:
bearerAuth
query Parameters
page
integer

A page number within the paginated result set.

per_page
integer

Number of results to return per page.

Responses

Response samples

Content type
application/json
{
  • "count": 123,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "results": [
    ]
}

Cartridges

This section contains endpoints for listing Cartridges.

cartridges_list

List of all resin cartridges associated with my account

Authorizations:
bearerAuth
query Parameters
page
integer

A page number within the paginated result set.

per_page
integer

Number of results to return per page.

Responses

Response samples

Content type
application/json
{
  • "count": 123,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "results": [
    ]
}

Events

This section contains endpoints for listing Events.

events_list

List of all events associated with my account

Authorizations:
bearerAuth
query Parameters
cartridge
string

Filter by resin cartridge serial

date__gt
string <date-time>

Filter by date greater than date specified (ISO 8601 Format)

date__lt
string <date-time>

Filter by date less than date specified (ISO 8601 Format)

page
integer

A page number within the paginated result set.

per_page
integer

Number of results to return per page.

print_run
string

Filter by print id

printer
string

Filter by printer serial

tank
string

Filter by resin tank serial

type
string

Filter by Event Type

Responses

Response samples

Content type
application/json
{
  • "count": 123,
  • "next": "http://api.example.org/accounts/?page=4",
  • "previous": "http://api.example.org/accounts/?page=2",
  • "results": [
    ]
}

Printer Groups

This section contains endpoints for managing Printer Groups.

groups_list

List of all groups for my account.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

groups_create

Create a group for my account, and make me an administrator.

Authorizations:
bearerAuth
Request Body schema:
required
name
required
string non-empty

Responses

Request samples

Content type
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "has_fleet_control": true,
  • "has_fleet_control_updated_by": 0
}

groups_bulk_add_printers_create

Move Printer(s) to a Printer Group. Notes: Request sender needs to be admin of target group and all of the Printers’ groups.

Authorizations:
bearerAuth
Request Body schema:
required
target_group
required
string <uuid>
printers
required
Array of any

Responses

Request samples

Content type
{
  • "target_group": "61e94a6e-8012-42fa-8fa7-642d2587bef0",
  • "printers": [
    ]
}

groups_partial_update

Update a group administered by my account.

Authorizations:
bearerAuth
path Parameters
group_id
required
string <uuid>

A UUID string identifying this workgroup.

Request Body schema:
name
string or null non-empty
remote_print_enabled_override
string or null non-empty

Responses

Request samples

Content type
{
  • "name": "string",
  • "remote_print_enabled_override": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "remote_print_enabled_override": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "memberships": [
    ],
  • "printers": [
    ],
  • "invitations": [
    ],
  • "has_fleet_control": true,
  • "has_fleet_control_updated_by": 0,
  • "settings": {
    }
}

groups_destroy

Delete a group administered by my account.

Authorizations:
bearerAuth
path Parameters
group_id
required
string <uuid>

A UUID string identifying this workgroup.

Responses

groups_members_create

Invite a user into my group.

Authorizations:
bearerAuth
path Parameters
group_id
required
string <uuid>

A UUID string identifying this Printer Group

Request Body schema:
required
user
required
string non-empty

Email address of the member to invite

is_admin
boolean

Change if the member is an administrator

Responses

Request samples

Content type
{
  • "user": "string",
  • "is_admin": true
}

Response samples

Content type
application/json
{
  • "is_admin": true,
  • "user": "string",
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string"
}

groups_members_update

Update a membership in an administered group. Warning: You cannot revoke the administrator right of yourself if there are no other administrators!

Authorizations:
bearerAuth
path Parameters
group_id
required
string <uuid>

A UUID string identifying this Printer Group

Request Body schema:
required
user
required
string non-empty

Email address of the member to update

is_admin
boolean

Change if the member is an administrator

Responses

Request samples

Content type
{
  • "user": "string",
  • "is_admin": true
}

Response samples

Content type
application/json
{
  • "is_admin": true,
  • "user": "string",
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string"
}

groups_members_destroy

Delete a membership in an administered group.

Authorizations:
bearerAuth
path Parameters
group_id
required
string <uuid>

A UUID string identifying this Printer Group

Request Body schema: application/json
user
required
string

Email address of the member to remove

Responses

Request samples

Content type
application/json
{
  • "user": "john.doe@example.com"
}

groups_queue_list

Returns a list of all items in the queue of a Printer Group. If the Group Queue feature is disabled for the group, the queue is considered empty and an empty list is returned.

Authorizations:
bearerAuth
path Parameters
group_id
required
string <uuid>

A UUID string identifying this Printer Group

Responses

Response samples

Content type
application/json
[
  • {
    }
]