FAQ - Frequently Asked Questions - Digital Factory¶

How do I obtain the status of my printers?¶

To get the current status of all printers in a remote cluster you can use the Connect API. The response to this endpoint will contain the status of all printers.

GET https://api.ultimaker.com/connect/v1/clusters

This end-point is documented here: https://docs.api.ultimaker.com/connect/spec.html#operations-default-getClusters

This provides only the basic data and status of the printers and the current print job. The following end-point gives detailed information about a printer including its print job queue, recent print job history (maximum 10 print jobs), and firmware status.

GET https://api.ultimaker.com/connect/v1/clusters/{cluster_id}/status

This end-point is documented here: https://docs.api.ultimaker.com/connect/spec.html#operations-default-getClusterStatus

Info

We currently do not support pushing of status updates via web socket technology towards user interfaces. To reduce complexity only full status objects can be polled from this endpoint instead of sending deltas. To build an interface that contains fresh status information we advice to poll the status endpoint every ~60 seconds.

How do I upload and store G-code or UFP files?¶

The API offers an endpoint to request a storage upload location. The response of this endpoint will provide a URL that can be used to upload the actual G-code or UFP file to. It also contains a job ID that can be used to download the G-code or UFP at a later point. This two-stage upload process gives the client control over the upload method (resumable vs one-time) and bandwidth.

First, do a call to receive a storage location:

PUT https://api.ultimaker.com/cura/v1/jobs/upload

Request:

{
    "data": {
        "job_name": "(UMS5)_UltiBot.upf",
        "file_size": 1950302,
        "content_type": "application/x-ufp",
        "origin": "https://your-domain.com"
    }
}

Response:

{
    "data": {
        "job_name": "(UMS5)_UltiBot.upf",
        "file_size": 1950302,
        "content_type": "application/x-ufp",
        "origin": "https://your-domain.com",
        "status": "uploading",
        "upload_url": "https://storage.googleapis.com/example-bucket/example-file..."
    }
}

Now you can upload the actual file to the upload_url from the response. Make sure that all the headers match the information provided earlier!

PUT https://storage.googleapis.com/example-bucket/example-file...
Content-Type: application/x-ufp
Content-Length: 1950302
Origin: https://your-domain.com

Info

The origin field is optional for backwards compatibility reasons, but we strongly advice to use it for enhanced security. It is required when performing the file upload from a browser front-end (as browsers always add an Origin header to HTTP requests).

After the file upload, you can confirm that it was successful by polling the status of the print job. You will now see that the status field has been set to uploaded, and a download_url is available.

GET https://api.ultimaker.com/cura/v1/jobs/{job_id}

Response:

{
    "data": {
        "job_name": "(UMS5)_UltiBot.upf",
        "file_size": 1950302,
        "content_type": "application/x-ufp",
        "origin": "https://your-domain.com",
        "status": "uploaded",
        "download_url": "https://storage.googleapis.com/example-bucket/example-file..."
    }
}

How do I upload and store STL files?¶

Uploading STL, or other library files, works very similar to uploading G-code or UFP files, however the endpoints use files instead of jobs:

PUT https://api.ultimaker.com/cura/v1/files/upload
GET https://api.ultimaker.com/cura/v1/files/{file_id}

Info

Ultimaker does not offer a cloud slicing service for uploaded STL files. You will need to slice them in Ultimaker Cura, and then upload the resulting G-code or UFP file via the API as well.

Which file types can I upload?¶

The following file types are supported. You must use the correct mimetype in the upload request and as header in the actual file upload to storage.

Toolpaths¶

These files go to /jobs/upload.

Extension(s)	Mimetype	Type
`.gcode`	text/plain	Toolpath
`.gcode.gz`	application/gzip	Toolpath
`.ufp`	application/x-ufp	Toolpath

Project files¶

These files go to /files/upload.

Extension(s)	Mimetype	Type
`.3mf`	application/vnd.ms-package.3dmanufacturing-3dmodel+xml	Mesh
`.stl`	model/stl	Mesh
`.jpg` `.jpeg`	image/jpeg	Image
`.png`	image/png	Image
`.pdf`	application/pdf	Document
`.doc`	application/msword	Document
`.docx`	application/vnd.openxmlformats-officedocument.wordprocessingml.document	Document
`.xls`	application/vnd.ms-excel	Document
`.xlsx`	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	Document
`.ppt`	application/vnd.ms-powerpoint	Document
`.pptx`	application/vnd.openxmlformats-officedocument.presentationml.presentation	Document
`.txt`	text/plain	Document

How do I send a print job to a connected printer?¶

Upload a toolpath file using the /jobs/upload endpoint of the Cura API as documented above to obtain a job_id.
Find the ID of the printer (cluster_id) you want to send the print job to using the /clusters endpoint of the Connect API.
Send the print job to the printer:

POST https://api.ultimaker.com/connect/v1/clusters/{cluster_id}/print/{job_id}

How can I see the progess of a print job?¶

First fetch the status of the print job:

GET https://api.ultimaker.com/connect/v1/clusters/{cluster_id}/print_jobs/{cluster_job_id}

This end-point is documented here: https://docs.api.ultimaker.com/connect/spec.html#operations-default-getPrintJobDetails

The detailed information about the print job instance contains a time_elapsed and time_total (seconds). The progress percentage of the print job can be computed from these values.

Can I upload a UFP or G-code directly in the Digital Factory web interface?¶

Yes. You can use the Library section of the Digital Factory to upload toolpath files. From there on, you can send them to connected printer directly, or use the API.

Will the ID of a printer stay the same?¶

There are several IDs related to printers, each with a different lifecycle:

cluster_id: This ID is generated when a printer is connected to the Digital Factory by a user. It will will be the same until the printer is disconnected manually from the user account, or if the printer goes through a factory reset or Digital Factory reset via the printer display.
uuid: This is the unique ID the printer assigned to itself. It will stay the same when re-connected to the Digital Factory, but it will change when the printer goes through a factory reset via the printer display.
(cluster_)host_guid: This is the unique ID generated during printer manufacturing. Only replacing the main electronics board will reset this ID.

Info

We are planning changes to how cluster_id works to make it more persistent accross reconnects. This will make it easier for API integrations to use this field and no longer need the other ID fields.

How long is a job ID valid for?¶

Job IDs are unique to an uploaded print job file (G-code or UFP) and will never expire, unless you remove the print job via the library UI or API.

Is there a sandbox environment with dummy printers?¶

Currently there is no sandbox environment with dummy printers. An actual printer connected to your account is needed to do meaningful interaction with the APIs related to remote printing. You could build a custom virtual printer and connect it, but we recommending testing with actual printers to make sure you test with real-world printer behaviour. Especially state changes are hard to simulate.

How can I generate and download a report?¶

The process of generating a report is performed asynchronously, involving several steps:

Initiate the report generation by making a request to the following endpoint: https://docs.api.ultimaker.com/reporting/spec.html#operations-default-createReport. This request should include a list of cluster/printer IDs, which can be obtained from: https://docs.api.ultimaker.com/connect/spec.html#operations-default-getClusters. Additionally, specify the type of report and the desired date range. The response to this call will include a report_id, which serves as a unique identifier for the report.
Continuously check the status of the report by polling the endpoint: https://docs.api.ultimaker.com/reporting/spec.html#operations-default-getReport, using the report_id obtained in the previous step. The generation process is considered complete when the status field of the response is set to success. At this point, the download_url field will contain a valid URL.
Access the provided download_url to retrieve the CSV file associated with the generated report. Download the file for further analysis or processing.

A complete working example of this can be found in the generateReport() method in https://github.com/Ultimaker/digital-factory-sdk/blob/master/typescript/src/digital-factory.ts .

How can I get a webcam image?¶

Obtaining a webcam image from a printer involves an asynchronous process. Initially, a command is sent to the printer to request the webcam image. Subsequently, the result is retrieved by polling until the process is completed.

The following steps provide a more detailed explanation:

Dispatch a webcam action to the printer by specifying the cluster ID and the printer ID. This action is executed through the endpoint available at https://docs.api.ultimaker.com/connect/spec.html#operations-default-printerAction. The response includes the status of the action and an action_id.
Continuously check the status of the running action using the action status endpoint: https://docs.api.ultimaker.com/connect/spec.html#operations-default-getActionStatus. The action is considered complete and successful when the status field indicates "success". At this point, the status_details.value.image_url field will provide the URL where the image can be accessed.
Download the image from the provided image_url.

To see a fully functional implementation of this process, refer to the getWebcamImage() method available at getWebcamImage() method in https://github.com/Ultimaker/digital-factory-sdk/blob/master/typescript/src/digital-factory.ts .