FAQ - Digital Factory¶

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 do I obtain the status of a running print job¶

To get the current status of all printers and print jobs in a remote cluster you can use the Connect API. The response to this endpoint will contain the full status of all printers and print jobs, including recent history (max. 10 print jobs) for newer firmware versions.

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

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.

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.