NAV
cURL

Getting Started

Welcome to the SimplyPrint API!

This documentation goes through authenticating and how to use the API. To get started you'll need an API key.

Getting an API key

To get an API key you'll need a SimplyPrint account that is either a member of an organization or has at least the SimplyPrint Pro plan.

To create your own API key you first need a SimplyPrint account, you can go to your account settings and create a new API key.

The base URL

The base URL for the SimplyPrint API is https://api.simplyprint.io/{id}/.

To use the base API at https://api.simplyprint.io, you will need to specify an id.

The id represents the unique identifier for the company that you are using the API key for. This id is used to access the specific functionality within the API that is associated with the company.

The endpoint represents the specific functionality that you want to access within the API. There are various endpoints available, each with its own specific purpose and functionality.

For example, if you want to access the account/Test endpoint for a company with an id of 123, you would use the following API endpoint:

https://api.simplyprint.io/123/account/Test

If you are part of an organization, you might need to ask your organization administrator to allow API access for your account for the organization.

Test your API key

curl {base_url}/account/Test \
  --header 'X-API-KEY: {API_KEY}'

Success return:

{
  "status": true,
  "message": "Your API key is valid!"
}

Error return in case of an invalid or missing API key:

{
  "status": false,
  "message": "No API key provided, or not logged in"
}

Error return in case of missing permissions for the organization:

{
  "status": false,
  "message": "You don't have access to this account"
}

To verify that your API key is valid and that you have access to the desired organization, you can make a request to the /account/Test endpoint.

To make any request to the SimplyPrint API, you will need to include your API key in the request header. You can do this by including the X-API-KEY header in your request. On the right side of this page, you can see an example of how to make a request to the /account/Test endpoint using cURL.

If you are unable to successfully make a request to the /account/Test endpoint using the provided example, there may be a few possible issues:

If you are unable to resolve the issue after troubleshooting these potential issues, you may need to contact your organization administrator for further assistance. Otherwise, feel free to contact us via our helpdesk.

Printers

Get printer info

curl https://api.simplyprint.io/{id}/printers/Get \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "page": 1,
  "page_size": 10,
  "search": "Printer 1"
}

Success response

{
  "status": true,
  "message": null,
  "page_amount": 1,
  "data": [
    {
      "id": 385,
      "sort_order": 6,
      "printer": {
        "name": "Mini Printer 1",
        "state": "printing",
        "group": 99,
        "position": 6,
        "api": "OctoPrint",
        "ui": "OctoPrint",
        "ip": "10.78.16.46",
        "public": 1,
        "machine": "Raspberry Pi 4 Model B Rev 1.2",
        "online": true,
        "region": "eu-west-2",
        "firmware": "Virtual Marlin",
        "spVersion": "4.0.5",
        "temps": {
          "ambient": 22,
          "current": {
            "tool": [
              210
            ],
            "bed": null
          },
          "target": {
            "tool": [
              210
            ],
            "bed": null
          }
        },
        "hasPSU": 1,
        "psuOn": true,
        "hasFilSensor": true,
        "filSensor": true,
        "filamentRetraction": 250,
        "model": {
          "id": 91,
          "name": "Fabrikator Mini",
          "brand": "Turnigy",
          "bedSize": [
            80,
            80
          ],
          "bedType": "square",
          "maxHeight": 80,
          "image": "https:\/\/cdn.simplyprint.io\/i\/printer_types\/turnigy\/fabrikator_mini\/silhouette_sm.png?cacheid=5fe9e77f49198",
          "hasHeatedBed": false,
          "extruders": 1,
          "extruderSettings": null,
          "maxToolTemp": 240,
          "maxBedTemp": 0,
          "filamentWidth": 1.75,
          "nozzleDia": 0.4,
          "axes": {
            "e": {
              "inverted": false,
              "speed": 5
            },
            "x": {
              "inverted": false,
              "speed": 100
            },
            "y": {
              "inverted": false,
              "speed": 100
            },
            "z": {
              "inverted": false,
              "speed": 3.5
            }
          },
          "screwOffset": 35,
          "filamentRetraction": 250,
          "customBoundingBox": false,
          "extrudeAbs": 0,
          "originCenter": 0,
          "bedBelt": 0,
          "fwRetract": 0,
          "extrusionType": 1,
          "noControl": 0
        },
        "hasCam": 1,
        "hasQueue": {
          "items": 6,
          "fits": true
        },
        "health": {
          "usage": 24,
          "temp": 61,
          "memory": 19
        },
        "unsupported": 0,
        "latency": null,
        "outOfOrder": 0
      },
      "filament": null,
      "job": {
        "id": 552252,
        "uid": "da69d2a4-e07e-48ff-128a-f88fab1b8f20",
        "state": "printing",
        "file": "Benchy.15mm_PLA_MK3S_7h40m.gcode",
        "percentage": 50,
        "time": 12627,
        "canPreview": true,
        "layer": null
      },
      "tags": {
        "nozzle": 0.6,
        "material": [
          {
            "ext": 0,
            "type": 123,
            "color": "Green",
            "hex":"#4CAF50"
          }
        ],
        "custom": [1, 2, 3]
      }
    },
    ...
  ]
}

This endpoint returns a list of printers based on the given parameters.

Request

POST /{id}/printers/Get

Query parameters

Parameter Type Required Description
pid integer no Optional printer ID if you want to get info for a single printer.

Request body

Parameter Type Required Description
page integer no Page number to get. Leave empty for page 1.
page_size integer no Number of printers per page. (Between 1 and 100)
Default: 10
search string no Search string to filter printers by.

Response

Note that data will be an object if pid is specified, otherwise it will be an array.

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data object or array Printer object(s).
data.*.id integer Printer ID.
data.*.sort_order integer The printer's sort index.
data.*.printer object Printer object.
data.*.printer.name string Printer's name.
data.*.printer.state string Printer's state.
data.*.printer.group integer Printer's group ID.
data.*.printer.position integer Printer's position in the group.
data.*.printer.api string Printer's API type.
data.*.printer.ui string Printer's UI type.
data.*.printer.ip string Printer's local IP address.
data.*.printer.public boolean Whether the printer is shown on the company hub.
data.*.printer.machine string Printer's machine type.
data.*.printer.online boolean Whether the printer is online.
data.*.printer.region string What region the printer is online in.
data.*.printer.firmware string Printer's firmware version.
data.*.printer.spVersion string Printer's SimplyPrint version.
data.*.printer.temps object Printer's current temperatures.
data.*.printer.hasPSU boolean Whether the printer has a SimplyPrint connected PSU.
data.*.printer.psuOn boolean Whether the printer's PSU is on.
data.*.printer.hasFilSensor boolean Whether the printer has a filament sensor.
data.*.printer.filamentRetraction integer Printer's filament retraction distance.
data.*.printer.model string Printer's model.
data.*.printer.hasCam boolean Whether the printer has a camera.
data.*.printer.hasQueue object Data about the printer's queue. Null if the printer doesn't have a queue.
data.*.printer.hasQueue.items integer Number of items in the printer's queue.
data.*.printer.hasQueue.fits boolean Whether the printer can physically fit any items in its queue.
data.*.printer.health object Printer's health data. (CPU usage, temperature, memory usage)
data.*.printer.unsupported boolean Whether the printer is unsupported.
data.*.printer.latency integer Printer's latency.
data.*.printer.outOfOrder boolean Whether the printer is out of order.
data.*.filament object Printer's filament data.
data.*.job object Printer's current job data. See Get Print Jobs for more info.
data.*.tags object nullable

Start print / create job

curl https://api.simplyprint.io/{id}/printers/actions/CreateJob?pid=1234&filesystem=291 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "pid": [1234, 1235],
  "filesystem": "196a1dd0b93a66c19192a39fa4c16e71"
}

Success response

{
  "status": true,
  "message": null,
  "files": [
    {
      "name": "Benchy.gcode",
      "analysis": {
        "slicer": "Simplify3D",
        "filament": [
          60
        ],
        "estimate": 240,
        "movement": {
          "mRelative": 0,
          "eRelative": 0
        },
        "temps": {
          "tool": {
            "T0": 210
          },
          "bed": 50,
          "pset": 1
        },
        "modelSize": {
          "x": 151,
          "y": 16,
          "z": 5
        },
        "printArea": {
          "maxX": 156.05,
          "minX": 5,
          "maxY": 157.86,
          "minY": 142.14,
          "maxZ": 5,
          "minZ": 0.2
        },
        "minDeltaRadius": 313.91,
        "v": 5
      },
      "printers": [
        1234,
        1235        
      ],
      "queued": false
    }
  ],
  "jobIds": [
    495462,
    495463
  ]
}

This endpoint can be used to create a print job for one or more printers. The printers have to be in the operational state.

Request

POST /{id}/printers/actions/CreateJob

To start a print job you must either specify a filesystem ID, a queue_file ID file or set next_queue_item to true.

Parameter Type Required Description
pid integer or integer[] yes The ID(s) of the printer to create the job for.
filesystem string no The filesystem ID of the file to print.
queue_file integer no The queue ID of the queue item to print.
next_queue_item boolean no If true, the next queue item will be printed.
This requires the Print Farm plan

Extra settings for next_queue_item

You can specify these parameters if next_queue_item is true. Note that you can specify more/all of the below parameters.

Parameter Type Required Description
analysis_strict boolean no Match the next item that has a valid gcode analysis.
Defaults to true
fit_strict boolean no Match the next item if it fits on the printers print area.
Defaults to true
temps_strict boolean no Match the next item where the printer can reach the temperatures specified in the gcode.
Defaults to true
filament_strict boolean no Match the next item that was sliced for the same filament type that the printer is assigned to in SimplyPrint.
Defaults to false
filament_temps_strict boolean no Match the next item that has the same filament temperatures as the printer has in SimplyPrint.
Defaults to false

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.
files array Array of started print job objects.
files[].name string The name of the file.
files[].analysis object The analysis of the file. This has been documented in the Get queue items endpoint.
files[].printers integer[] The IDs of the printers that the print job was started on.
files[].queued boolean Whether the print job was from print queue.
jobIds integer[] The IDs of the print jobs that were started.

Pause print job

curl https://api.simplyprint.io/{id}/printers/actions/Pause?pid=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}

This endpoint can be used to pause one or multiple print jobs. The printers have to be in the PRINTING state.

Request

POST /{id}/printers/actions/Pause

Query parameters

Parameter Type Required Description
pid integer or integer[] yes The ID(s) of the printer to pause. Pause multiple printers by comma separating printer ids.
Printer must be in PRINTING state

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Resume print job

curl https://api.simplyprint.io/{id}/printers/actions/Resume?pid=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}

Request

POST /{id}/printers/actions/Resume

Query parameters

Parameter Type Required Description
pid integer or integer[] yes The ID(s) of the printer to resume. Resume multiple printers by comma separating printer ids.
Printer must be in PRINTER_PAUSED state

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Cancel print job

curl https://api.simplyprint.io/{id}/printers/actions/Cancel?pid=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "reason": 3,
  "comment": "Cancel comment"
}

Success response

{
  "status": true,
  "message": null
}
Required permission Description
CANCEL_OTHERS_PRINTS Need permission to cancel other users' prints if the print job was started by another user.

This endpoint can be used to cancel one or multiple print jobs. The printers have to be in the PRINTING, PAUSED or PAUSING state.

Request

POST /{id}/printers/actions/Cancel

Query parameters

Parameter Type Required Description
pid integer or integer[] yes The ID(s) of the printer to cancel. Cancel multiple printers by comma separating printer ids.
Printer must be in PRINTING, PAUSED or PAUSING state

Request body

Field Type Required Description
reason integer no The reason for cancelling the print job. See Cancel reasons. Depending on the require_cancel_reason organization setting, this field may be required.
comment string no A comment for the cancel reason. Depending on the require_comment organization setting, this field may be required.
Max length: 500 characters

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Clear print bed

curl https://api.simplyprint.io/{id}/printers/actions/ClearBed?pid=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "success": true,
  "rating": 4
}

Success response

{
  "status": true,
  "message": null
}

This endpoint can be used to clear the print bed of a printer.

Request

POST /{id}/printers/actions/ClearBed

Query parameters

Parameter Type Required Description
pid integer yes The ID(s) of the printer to clear, comma separated. These printers have to be in either the operational or offline states.

Request body

Field Type Required Description
success boolean no True if the print was successful.
Default: false
rating integer no The rating of the print. Don't send this field if you do not want to rate the print.

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Delete / disconnect printer

curl https://api.simplyprint.io/{id}/printers/Delete?pid=1234&just_connection=1 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}
Required permissions
PRINTER_EDIT

This endpoint can be used to delete a printer from the database, or to disconnect a pi from a printer. This is useful if you want to change the printer that is connected to a pi.

Request

GET /{id}/printers/Delete

Parameter Type Required Description
pid integer yes The ID of the printer to delete.
just_connection integer no If set to 1, only the Pi connection will be deleted. Otherwise, the printer will be permanently deleted.
Default: 0

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Cancel reasons

ID Description
1 Print failed
2 Regretted print
3 No filament extruded / nozzle clog
4 Fell of the plate
5 Not enough filament
6 Other

Filament

List Filaments

curl https://api.simplyprint.io/{id}/filament/GetFilament \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "showid": true,
  "is_kg": false,
  "brands": {
    "test brand": 1,
    ...
  },
  "types": {
    "PLA": 1,
    ...
  },
  "filament": {
    "3017": {
      "id": 3017,
      "uid": "PL23",
      "type": {
        "id": 5637,
        "name": "PLA"
      },
      "brand": "test brand",
      "colorName": "test color",
      "colorHex": "#000000",
      "dia": 1.75,
      "density": 1.24,
      "temps": {
        "nozzle": 210,
        "bed": 65,
        "flNozzle": 210,
        "flBed": 65
      },
      "slicing": {
        "printSpeed": 70,
        "finishRate": 0.5,
        "minSpeed": 15
      },
      "total": 335284,
      "left": 234699,
      "extruder": 0,
      "bought": 1630447200,
      "created": 1630508337,
      "printer": 0,
      "nfc": 0,
      "qr": 0,
      "prodId": ""
    },
    ...
  }
}

This endpoint returns a list of all filaments as well as filament types and brands.

Request

GET /{id}/filament/GetFilament

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
showid boolean Whether to show filament id. (Frontend data)
is_kg boolean Whether to show filament in kg. (Frontend data)
brands object Filament brands.
brands.{brand} integer Number of filaments with {brand}.
types object Filament types such as PLA, ABS, PETG, etc.
types.{type} integer Number of filaments with {type}.
filament object Filament data where each key is a filament id.
filament.{id} object Filament data.
filament.{id}.id integer Filament id. (same as {id})
filament.{id}.uid string Four character code that is used to identify the filament. Refered to as filament id in the frontend.
filament.{id}.type object Filament type.
filament.{id}.type.id integer Filament type id.
filament.{id}.type.name string Filament type name.
filament.{id}.brand string Filament brand.
filament.{id}.colorName string Filament color name.
filament.{id}.colorHex string Filament color hex code.
filament.{id}.dia float Filament diameter.
filament.{id}.density float Filament density.
filament.{id}.temps object Filament temperatures.
filament.{id}.temps.nozzle integer Filament nozzle temperature.
filament.{id}.temps.bed integer Filament bed temperature.
filament.{id}.temps.flNozzle integer Filament first layer nozzle temperature.
filament.{id}.temps.flBed integer Filament first layer bed temperature.
filament.{id}.slicing object Filament slicing settings.
filament.{id}.slicing.printSpeed integer Filament print speed.
filament.{id}.slicing.finishRate float Filament finish rate.
filament.{id}.slicing.minSpeed integer Filament minimum speed.
filament.{id}.total integer Total filament length in mm.
filament.{id}.left integer Left filament length in mm.
filament.{id}.extruder integer Which extruder the filament is assigned to.
filament.{id}.bought integer Timestamp of when the filament was bought.
filament.{id}.created integer Timestamp of when the filament was created.
filament.{id}.printer integer Which printer the filament is assigned to.
filament.{id}.nfc integer Whether the filament has NFC.
filament.{id}.qr integer Whether the filament has QR.
filament.{id}.prodId string Filament product id.

Create or Update Existing Filament

curl https://api.simplyprint.io/{id}/filament/Create \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request Body

{
  "color_name": "Porcelain White",
  "color_hex": "#E5E5E5",
  "color_standard": "NCS S 1000-N",
  "width": 1.75,
  "density": 1.24,
  "bought_at": "2022-12-24",
  "filament_type": "rPLA",
  "cost": 23,
  "currency": "USD",
  "custom_note": "This is a note",
  "prod_id": "",
  "brand": "lostboyslab",
  "brand_id": 1,
  "filgroup_id": 13,
  "spool_id": 44,
  "slicing_settings": {
    "nozzle_temp": 200,
    "nozzle_fl_temp": 200,
    "bed_temp": 60,
    "bed_fl_temp": 60,
    "print_speed": 70,
    "finish_rate": 0.5,
    "min_speed": 15
  },
  "amount": 1,
  "total_length_type": "kg",
  "left_length_type": "percent",
  "total_length": 1,
  "length_used": 57
}

Success response

{
  "status": true,
  "message": null,
  "filament_ids": [
    "NGGY"
  ],
  "qr_gen": 1
}

This endpoint can be used to create or update existing filament.

To update existing filament, you need to provide a fid query parameter, which is the filament id of the filament you want to update.

Required permissions
CREATE_FILAMENT

Request

POST /{id}/filament/Create

Query Parameters

Parameter Type Required Description
fid string no Filament id of the filament you want to update.

Request Body

Parameter Type Required Description
color_name string yes Filament color name.
Max 64 characters
color_hex string yes Filament color hex code.
color_standard string no Filament color standard.
width float (enum) yes Filament width.
Value has to be one of [1.75, 2.85, 3.00]
density float yes Filament density.
bought_at string no Date of purchase.
Format: YYYY-MM-DD
filament_type string yes Filament type.
cost float no Cost of filament.
currency string no Currency of cost.
Max 3 characters
custom_note string no Custom note.
Max 1000 characters
prod_id string no Filament product id.
brand string yes Filament brand.
brand_id integer no Filament brand id.
filgroup_id integer no Target SimplyPrint filament group id to insert filament into.
spool_id integer no Filament spool id.
slicing_settings object yes Slicing settings.
slicing_settings.nozzle_temp integer yes Nozzle temperature.
slicing_settings.nozzle_fl_temp integer yes Nozzle first layer temperature.
slicing_settings.bed_temp integer yes Bed temperature.
slicing_settings.bed_fl_temp integer yes Bed first layer temperature.
slicing_settings.print_speed integer yes Print speed.
slicing_settings.finish_rate float yes Finish rate.
slicing_settings.min_speed integer yes Minimum speed.
amount integer yes Amount of filament.
total_length_type string yes Total length type.
left_length_type string yes Left length type.
total_length float yes Total length.
length_used float yes Length used.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
filament_ids array Array of filament ids.
qr_gen integer Used for frontend, not important.

Delete Filament

curl https://api.simplyprint.io/{id}/filament/Delete?fid=4519 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}

This endpoint deletes a filament specified by the fid parameter.

Required permissions
CREATE_FILAMENT

Request

GET /{id}/filament/Delete

Parameter Type Required Description
fid integer yes Filament id

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Assign Filament(s) To Printer

curl https://api.simplyprint.io/{id}/filament/Assign?pid=5123&fid=21812,31253 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "extruder": {
      "21812": 0,
      "31253": 1
    }
}

Success response

{
  "status": true,
  "message": null
}

This endpoint assigns filament(s) to a printer.

Required permissions
CHANGE_FILAMENT

Request

POST /{id}/filament/Assign

The request has both query parameters and a request body.

Query parameters

Parameter Type Required Description
pid integer yes Printer id.
fid integer yes Filament id(s), comma separated.

Request body

Parameter Type Required Description
extruder object yes Which filament to assign to which extruder.
extruder.{fid} integer yes Which extruder id to assign {fid} to.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Unassign Filament From Printer

curl https://api.simplyprint.io/{id}/filament/Unassign?fid=21812 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}

This endpoint unassigns a filament from a printer by filament id.

Required permissions
CHANGE_FILAMENT

Request

GET /{id}/filament/Unassign

Parameter Type Required Description
fid integer yes Filament id to unassign.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Files

List Files and Folders

curl https://api.simplyprint.io/{id}/files/GetFiles?f=123&search=benchy \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "files": [
    {
      "id": "d82ab9e1cc3c20850d94d5cf539390c0",
      "name": "3DBenchy",
      "ext": "stl",
      "type": "model",
      "size": 11285384,
      "created": "December 23, 2022, 17:35",
      "createdint": 1671813336,
      "printData": {
        "printsDone": 0,
        "printsCancelled": 0,
        "printsFailed": 0,
        "timesSliced": 0
      },
      "user_id": 123,
      "thumbnail": 1,
      "folder": 0,
      "user": 123,
    },
    {
      "id": "e82ab9e1cc3c20850d94d5cf539390c0",
      "name": "3DBenchy",
      "ext": "gcode",
      "type": "model",
      "size": 1285384,
      "created": "December 23, 2022, 18:00",
      "createdint": 1671813330,
      "printData": {
        "printsDone": 10,
        "printsCancelled": 5,
        "printsFailed": 0,
        "timesSliced": 0
      },
      "user_id": 123,
      "thumbnail": 1,
      "folder": 0,
      "user": 123,
      "forPrinters": [
        // list of printers IDs selected for file; key not present if no printers are selected 
        1,
        2,
        3
      ],
      "tags": {
        "nozzle": 0.6,
        "material": [
          {
            "ext": 0,
            "type": 123,
            "color": "Green",
            "hex":"#4CAF50"
          }
        ],
        "custom": [1, 2, 3]
      }
    }
  ],
  "folders": [
    {
      "id": 5290,
      "name": "random_folder_called_benchy",
      "items": {
        "files": 0,
        "folders": 0
      },
      "created": "December 23, 2022",
      "createdInt": 1671814215,
      "parent_folder_id": 0,
      "depth": 0
    }
  ],
  "path": [
    [
      "Your search...",
      0
    ]
  ],
  "sort_type": "",
  "space": 10000000000,
  "space_used": 131446609
}

This endpoint returns a list of files and folders in a given folder. If no folder is specified, the root folder is used.

Request

GET /{id}/files/GetFiles

Parameter Type Required Description
f integer no Folder ID to get files for. Defaults to 0 (root folder)
search string no Search string to filter files by.
global_search boolean no If true, search all files in the account, not just the folder specified by f.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
files array Array of file objects.
folders array Array of folder objects.
path array Array of arrays containing the path to the current folder.
sort_type string Sort type from user's settings.
space integer The total space available in bytes.
space_used integer The total space used in bytes.

Move File(s) to Folder

curl https://api.simplyprint.io/{id}/files/MoveFiles?files=d82ab9e1cc3c20850d94d5cf539390c0&folder=5290 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": "Moved 1 files"
}

This endpoint moves one or more files to a given folder.

Request

GET /{id}/files/MoveFiles

Parameter Type Required Description
files array yes Array of file IDs to move. Separate multiple IDs with a comma.
folder integer yes Folder ID to move files to.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Get Folder Details

curl https://api.simplyprint.io/{id}/files/GetFolder?id=5290 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "folder": {
    "id": 5290,
    "name": "org_folder_called_benchy",
    "org": true,
    "permissions": {
      "view": [
        112,
        151
      ],
      "upload": [
        112
      ],
      "modify": [
        112
      ]
    }
  }
}

This endpoint returns details about a given folder.

Request

GET /{id}/files/GetFolder

Parameter Type Required Description
id integer yes Folder ID to get details for.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
folder object Folder object.
folder.id integer Folder ID.
folder.name string Folder name.
folder.org boolean True if the folder is an organization folder.
Requires Print Farm plan
folder.permissions object null
folder.permissions.view array Array of group IDs that can view the folder.
folder.permissions.upload array Array of group IDs that can upload files to the folder.
folder.permissions.modify array Array of group IDs that can modify the folder.

Move Folder

curl https://api.simplyprint.io/{id}/files/MoveFolder?folder=5290&target=5291 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": "Moved folder 5298 to folder 5297"
}

This endpoint moves a folder to a given folder.

Please note that the root folder cannot be moved, but folders can be moved into the root folder by setting target=0. Also, folders cannot be moved into themselves.

Request

GET /{id}/files/MoveFolder

Parameter Type Required Description
folder integer yes Folder ID to move.
target integer yes Folder ID to move to.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Queue

Add item to queue

curl https://api.simplyprint.io/{id}/queue/AddItem \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "filesystem": "1a077dd6296417fe75555bf806b68089",
  "amount": 5,
  "group": 0
}

Success response

{
  "status": true,
  "message": null,
  "created_id": 1337
}

This endpoint adds a file to the queue. The file can either be a file on the filesystem or an uploaded stl/3mf/obj/gcode/gco/nc/npg file.

Note: if you want to specify which printer/printer type/printer model the print job should be assigned, you can edit the print job after it has been added to the queue.

Request

POST /{id}/queue/AddItem

Parameter Type Required Description
filesystem string no The filesystem id of the file to add to the queue.
amount integer no The amount of prints to add to the queue.
Default: 1
group integer no If you have Queue Groups - ID of the group the item should be added to.
Default: 0 - required if you have Queue Groups

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.
created_id integer The id of the created queue item

Get next queue item

curl https://api.simplyprint.io/{id}/queue/GetNextItems?p=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "settings": {
    "filament": false,
    "filamentTemps": false,
    "fit": true,
    "gcodeAnalysis": false,
    "printerTemps": false
  }
}

Success response

{
  "status": true,
  "message": null,
  "queue": {
    "total": 15,
    "printers": [
      385
    ],
    "matches": [
      {
        "id": 1212,
        "index": 5,
        "printer": 385,
        "match": true,
        "issues": [
          "size",
          "temps"
        ],
        "missed": 0,
        "name": "Benchy.gcode",
        "printed": 2,
        "left": 1
      }
    ]
  }
}

Failed response (Could not find any items that match the specified conditions)

{
  "status": true,
  "message": null,
  "queue": {
    "total": 15,
    "printers": [
      385
    ],
    "matches": [
      {
        "printer": 385,
        "match": false,
        "issues": [
          "size",
          "temps"
        ],
        "missed": 4
      }
    ]
  }
}

This endpoint gets the next item in the queue for the specified printer. The next item is the item that has the highest priority. The result will have skipped all items that do not meet the specified conditions.

Request

POST /{id}/queue/GetNextItems

Request parameters

Parameter Type Required Description
p integer[] yes Comma separated list of printer ids to get the next items for.

Request body

Parameter Type Required Description
settings object no Conditions that must be met for the next item.
settings.filament boolean no Must have enough filament.
Default: true
settings.filamentTemps boolean no Printer's filament temperature must match filament temperature of file.
Default: true
settings.fit boolean no Print must fit printer's bed.
Default: true
settings.gcodeAnalysis boolean no Must have gcode analysis.
Default: true
settings.printerTemps boolean no File must have a max temperature that is lower than the printer's max temperature.
Default: true
settings.tags boolean no Printer must match possible queue item tags (nozzle size, material data & custom tags).
Default: true

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.
queue object The queue object.
queue.total integer The total amount of items in the queue.
queue.printers integer[] The printer ids that were requested.
queue.matches array The next items for each printer.
queue.matches[].id integer The id of the next item. Only present if match is true.
queue.matches[].index integer The index of the item in the queue. Only present if match is true.
queue.matches[].printer integer The id of the printer that the item is for.
queue.matches[].match boolean True if a match was found.
queue.matches[].issues string[] The issues that are present in the item. Can also have values if an item was matched but would have been catched by other settings.
queue.matches[].missed integer The amount of items that were skipped.
queue.matches[].name string The name of the item. Only present if match is true.
queue.matches[].printed integer The amount of completed prints of this item (from print queue). Only present if match is true.
queue.matches[].left integer The amount of prints left (from print queue). Only present if match is true.

Get queue items

curl https://api.simplyprint.io/{id}/queue/GetItems?p=1234 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "queue": {
    "fits": true,
    "items": [
      {
        "id": 51293,
        "index": 1,
        "filename": "benchy.gcode",
        "note": null,
        "model": false,
        "printable": true,
        "left": 1,
        "printed": 0,
        "filesystem_id": "c00489ef361771ac098b5a60e6740757",
        "group": 0,
        "for": {
          "printers": [
            1234
          ],
          "models": [
            1234
          ],
          "groups": [
            1234
          ]
        },
        "analysis": {
          "slicer": "Simplify3D",
          "filament": [
            60
          ],
          "estimate": 240,
          "movement": {
            "mRelative": 0,
            "eRelative": 0
          },
          "temps": {
            "tool": {
              "T0": 210
            },
            "bed": 50,
            "pset": 1
          },
          "modelSize": {
            "x": 151,
            "y": 16,
            "z": 5
          },
          "printArea": {
            "maxX": 156.05,
            "minX": 5,
            "maxY": 157.86,
            "minY": 142.14,
            "maxZ": 5,
            "minZ": 0.2
          },
          "minDeltaRadius": 313.91,
          "v": 5
        },
        "user": "John Doe",
        "user_id": 1234,
        "tags": {
          "nozzle": 0.6,
          "material": [
            {
              "ext": 0,
              "type": 123,
              "color": "Green",
              "hex":"#4CAF50"
            }
          ],
          "custom": [1, 2, 3]
        }
      }
    ]
  }
}

This endpoint returns the queue for the specified or all printers.

Request

GET /{id}/queue/GetItems

Parameter Type Required Description
p integer no The printer id to get the queue for. If not specified, the queue for all printers will be returned.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.
queue object The queue object.
queue.fits boolean Whether any items in the queue can be printed on the printer. (due to space, temperature)
queue.items array An array of queue item objects.
queue.items[].id integer The queue item id.
queue.items[].index integer The queue item index.
queue.items[].filename string The queue item filename.
queue.items[].note string nullable
queue.items[].model boolean True if the queue item is a model.
queue.items[].printable boolean True if the queue is printable.
queue.items[].left integer The amount of prints left to print.
queue.items[].printed integer The amount of prints that have been printed.
queue.items[].filesystem_id string/null File id if print is from SimplyPrint filesystem.
queue.items[].group integer Possible ID of Queue Group.
queue.items[].for object For which printers, models and groups this queue item is for.
queue.items[].for.printers array An array of printer ids.
queue.items[].for.models array An array of printer model ids.
queue.items[].for.groups array An array of group ids.
queue.items[].analysis object The analysis object.
queue.items[].analysis.slicer string The slicer used to slice the file.
queue.items[].analysis.filament array An array of filament lengths.
queue.items[].analysis.estimate integer The estimated print time in seconds.
queue.items[].analysis.movement object The movement object.
queue.items[].analysis.temps object The temperatures object.
queue.items[].analysis.temps.tool object Temperature for each tool (extruder).
queue.items[].analysis.temps.bed integer Temperature for the bed.
queue.items[].analysis.modelSize object The model size object. Represented as x, y and z values in millimeters.
queue.items[].analysis.printArea object The print area object. Represented as maxX, minX, maxY, minY, maxZ and minZ values in millimeters.
queue.items[].analysis.minDeltaRadius float Minimum radius for delta printers.
queue.items[].analysis.v integer The analysis version.
queue.items[].user string The user name of who added the queue item.
queue.items[].user_id integer The user id of who added the queue item.
queue.items[].tags object nullable
queue.done_items array If groups GET is set, an array of done queue items, or ones where the last remaining item is being printed includes all the same fields as queue items, with a few extra;.
queue.done_items[].... Fields inherited from regular queue items.
queue.done_items[].size integer Byte-size used by this item - 0 if the file is from the filesystem.
queue.done_items[].ongoing boolean If the item is currently ongoing.
queue.done_items[].done UTC date nullable
queue.done_items[].expires UTC date nullable

Update queue item

curl https://api.simplyprint.io/{id}/queue/UpdateItem?job=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "for_groups": [
    1234
  ],
  "for_models": [
    1234
  ],
  "for_printers": [
    1234
  ]
}

Success response

{
  "status": true,
  "message": null
}

This endpoint updates the queue item with the specified id.

Request

POST /{id}/queue/UpdateItem

Query parameters

Parameter Type Required Description
job integer yes The queue item id to update.

Request body

Parameter Type Required Description
for_groups array no An array of group ids to assign the queue item to.
for_models array no An array of printer model ids to assign the queue item to.
for_printers array no An array of printer ids to assign the queue item to.
amount integer no The new amount to set.
amount integer no Set amount of "printed".

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Delete queue item

curl https://api.simplyprint.io/{id}/queue/DeleteItem?job=1234 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}

This endpoint deletes the queue item with the specified id.

Request

? /{id}/queue/DeleteItem

Parameter Type Required Description
job integer yes The queue item id to delete.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Change queue order

curl https://api.simplyprint.io/{id}/queue/SetOrder?job=1234&from=0&to=1 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
    "success": true,
    "message": null
}

This endpoint changes the order of the queue items by moving the queue item with the specified id.

Request

GET /{id}/queue/SetOrder

Parameter Type Required Description
job integer yes The queue item id to move.
from integer yes The current position of the queue item.
to integer yes The new position of the queue item.

Response

Parameter Type Description
success boolean True if the request was successful.
message string Success message or error message if success is false.

Empty queue

curl https://api.simplyprint.io/{id}/queue/EmptyQueue \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}
Required Permissions
PRINT_QUEUE_REMOVE_ALL

This endpoint empties the queue.

Request

GET /{id}/queue/EmptyQueue

Parameter Type Required Description
group integer no ID of Queue Group to empty.
**Default: 0 - required if you have Queue Groups

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Account

Create company groups

curl https://api.simplyprint.io/{id}/account/settings/groups/Create \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "ranks": [
    {
      "title": "name of group",
      "description": "group description",
      "sort_order": 3,
      "permissions": "{\"view_news\":true,\"org_admin\":true,\"panel_printing\":true,\"printer_restart\":true,\"printer_edit\":true,\"bed_leveling\":true,\"gcode_profiles\":true,\"printer_settings\":true,\"filament_settings\":true,\"change_filament\":true,\"create_filament\":true,\"see_filament_tab\":true,\"view_users\":true,\"change_user_rank\":true,\"manual_user_email_confirm\":true,\"invite_users\":true,\"delete_user\":true,\"org_user_registration_settings\":true,\"org_hub_settings\":true,\"org_rank_management\":true,\"org_view_statistics\":true,\"refill_quota\":true,\"custom_slicer_profiles\":true,\"org_profiles\":true,\"all_slicer_modes\":true,\"queue_remove_all\":true,\"org_api\":true,\"create_org_folder\":true,\"cancel_others\":true,\"see_who_printed\":true,\"max_print_size\":[],\"default_slicer_mode\":2}"
    }
  ]
}

Success response

{
  "status": true,
  "message": null,
  "data": [
    {
      "title": "name of group",
      "description": "group description",
      "company_id": 2,
      "company_type": 2,
      "sort_order": 3,
      "permissions": "{\"view_news\":true,\"org_admin\":true,\"panel_printing\":true,\"printer_restart\":true,\"printer_edit\":true,\"bed_leveling\":true,\"gcode_profiles\":true,\"printer_settings\":true,\"filament_settings\":true,\"change_filament\":true,\"create_filament\":true,\"see_filament_tab\":true,\"view_users\":true,\"change_user_rank\":true,\"manual_user_email_confirm\":true,\"invite_users\":true,\"delete_user\":true,\"org_user_registration_settings\":true,\"org_hub_settings\":true,\"org_rank_management\":true,\"org_view_statistics\":true,\"refill_quota\":true,\"custom_slicer_profiles\":true,\"org_profiles\":true,\"all_slicer_modes\":true,\"queue_remove_all\":true,\"org_api\":true,\"create_org_folder\":true,\"cancel_others\":true,\"see_who_printed\":true,\"max_print_size\":[],\"default_slicer_mode\":2}",
      "id": 319
    }
  ]
}
Required permissions
ORG_RANK_MANAGEMENT

This endpoint creates a new group in the company.

Request

POST /{id}/account/settings/groups/Create

Parameter Type Required Description
ranks array yes Array of groups to create.
ranks[].title string yes The name of the group.
ranks[].description string no The description of the group.
ranks[].sort_order integer yes The sort index of the group.
ranks[].permissions string yes JSON string of the permissions of the group. For more information, see Permissions.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data array Array of the created groups.

Update company groups

curl https://api.simplyprint.io/{id}/account/settings/groups/Update \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "ranks": [
    {
      "id": 319,
      "title": "TITLE",
      "description": "DESCRIPTION",
      "permissions": "{\"view_news\":true,\"org_admin\":true,\"panel_printing\":true,\"printer_restart\":true,\"printer_edit\":true,\"bed_leveling\":true,\"gcode_profiles\":true,\"printer_settings\":true,\"filament_settings\":true,\"change_filament\":true,\"create_filament\":true,\"see_filament_tab\":true,\"view_users\":true,\"change_user_rank\":true,\"manual_user_email_confirm\":true,\"invite_users\":true,\"delete_user\":true,\"org_user_registration_settings\":true,\"org_hub_settings\":true,\"org_rank_management\":true,\"org_view_statistics\":true,\"refill_quota\":true,\"custom_slicer_profiles\":true,\"org_profiles\":true,\"all_slicer_modes\":true,\"queue_remove_all\":true,\"org_api\":true,\"create_org_folder\":true,\"cancel_others\":true,\"see_who_printed\":true,\"max_print_size\":[],\"default_slicer_mode\":2}",
      "sort_order": 3,
    }
  ]
}

Success repsonse

{
  "status": true,
  "message": null,
  "data": [
    {
      "id": 319,
      "title": "NAME",
      "description": "DESCRIPTION",
      "company_id": 2,
      "company_type": 2,
      "permissions": "{\"view_news\":true,\"org_admin\":true,\"panel_printing\":true,\"printer_restart\":true,\"printer_edit\":true,\"bed_leveling\":true,\"gcode_profiles\":true,\"printer_settings\":true,\"filament_settings\":true,\"change_filament\":true,\"create_filament\":true,\"see_filament_tab\":true,\"view_users\":true,\"change_user_rank\":true,\"manual_user_email_confirm\":true,\"invite_users\":true,\"delete_user\":true,\"org_user_registration_settings\":true,\"org_hub_settings\":true,\"org_rank_management\":true,\"org_view_statistics\":true,\"refill_quota\":true,\"custom_slicer_profiles\":true,\"org_profiles\":true,\"all_slicer_modes\":true,\"queue_remove_all\":true,\"org_api\":true,\"create_org_folder\":true,\"cancel_others\":true,\"see_who_printed\":true,\"max_print_size\":[],\"default_slicer_mode\":2}",
      "sort_order": 3,
      "created": "2023-01-03 14:35:28"
    }
  ]
}
Required permissions
ORG_RANK_MANAGEMENT

This endpoint updates the groups in the company.

Request

POST /{id}/account/settings/groups/Update

Parameter Type Required Description
ranks array yes Array of groups to update.
ranks[].id integer yes The id of the group to update.
ranks[].title string no The name of the group.
ranks[].description string no The description of the group.
ranks[].permissions string no JSON string of the permissions of the group. For more information, see Permissions.
ranks[].sort_order integer no The sort index of the group.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data array Array of the updated groups.
data[].id integer The id of the group.
data[].title string The name of the group.
data[].description string The description of the group.
data[].company_id integer The id of the company.
data[].company_type integer The type of the company.
data[].permissions string JSON string of the permissions of the group. For more information, see Permissions.
data[].sort_order integer The sort order of the group.
data[].created string The date and time the group was created.

Get company groups

curl https://api.simplyprint.io/{id}/account/GetGroups \
  -X GET \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "groups": [
    {
      "id": 112,
      "name": "Administrator"
    },
    {
      "id": 151,
      "name": "Manager"
    },
    {
      "id": 153,
      "name": "User"
    }
  ]
}
Required permissions
ORG_RANK_MANAGEMENT

This endpoint returns a list of groups that exist in the company.

Request

GET /{id}/account/GetGroups

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
groups array Array of group objects.
groups[].id integer Group ID.
groups[].name string Group name.

Delete company group

curl https://api.simplyprint.io/{id}/account/settings/groups/Delete \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "id": 112,
  "replacementRankId": 151
}

Success response

{
  "status": true,
  "message": null,
}
Required permissions
ORG_RANK_MANAGEMENT

Request

POST /{id}/account/settings/groups/Delete

Parameter Type Required Description
id integer yes The id of the group to delete.
replacementRankId integer maybe The id of the group to replace the deleted group with.
This is only required if the group has users.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Get statistics

curl https://api.simplyprint.io/{id}/account/GetStatistics \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "users": [1234, 1235, 1945],
  "printers": [1234, 1235, 1945],
  "start_date": "1677629786",
  "end_date": "1677629786"
}

Success response

{
    "status": true,
    "message": null,
    "data": {
        "total_print_seconds": 1234,
        "total_filament_usage_gram": 1241.1231231,
        "print_job_count": 123,
        "regretted_print_jobs": 123,
        "failed_print_jobs": 123,
        "printer_error_print_jobs": 123,
        "done_print_jobs": 123,
        "date_range": {
            "from": "2023-02-22",
            "to": "2023-03-02",
            "general": false
        },
        "printers": {
            "3104": {
                "name": "Printer 1",
                "done": 0,
                "failed": 0,
                "printer_error": 0,
                "regretted": 0,
                "filament_usage_gram": 0
            },
            ...
        },
        "print_jobs": [
            {
                "date": "2023-02-27",
                "started": "2023-02-27 11:39:34",
                "ended": "2023-02-27 11:56:18",
                "cancelled": 1,
                "failed": 0,
                "cancel_reason_type": 5,
                "print_seconds": 1004,
                "filament_usage_gram": 0.03758012402132279
            },
            ...
        ]
    }
}

This endpoint returns statistics for the user / company.

Request

POST /{id}/account/GetStatistics

Parameter Type Required Description
users array no Array of user ids to get statistics for. Don't include this parameter to get statistics for all users.
printers array no Array of printer ids to get statistics for. Don't include this parameter to get statistics for all printers.
start_date string no The start date of the statistics. Provide a unix timestamp in seconds.
end_date string no The end date of the statistics. Provide a unix timestamp in seconds.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data object Statistics object.
data.total_print_seconds integer Total print seconds.
data.total_filament_usage_gram float Total filament usage in grams.
data.print_job_count integer Total print job count.
data.regretted_print_jobs integer Total regretted print job count.
data.failed_print_jobs integer Total failed print job count.
data.printer_error_print_jobs integer Total printer error print job count.
data.done_print_jobs integer Total successful print job count.
data.date_range object Date range object.
data.date_range.from string Start date of the statistics.
data.date_range.to string End date of the statistics.
data.date_range.general boolean True if the date range is general.
data.printers object Object of printer statistics.
data.printers.{id} object Printer statistics object.
data.printers.{id}.name string Printer name.
data.printers.{id}.done integer Successful print job count.
data.printers.{id}.failed integer Failed print job count.
data.printers.{id}.printer_error integer Printer error print job count.
data.printers.{id}.regretted integer Regretted print job count.
data.printers.{id}.filament_usage_gram float Filament usage in grams.
data.print_jobs array Array of print job statistics.
data.print_jobs[].date string Date of the print job.
data.print_jobs[].started string Start time of the print job.
data.print_jobs[].ended string End time of the print job.
data.print_jobs[].cancelled integer True if the print job was cancelled.
data.print_jobs[].failed integer True if the print job failed.
data.print_jobs[].cancel_reason_type integer The reason for cancelling the print job.
data.print_jobs[].print_seconds integer Print seconds.
data.print_jobs[].filament_usage_gram float Filament usage in grams.

Print Jobs

Get Print Jobs

curl https://api.simplyprint.io/{id}/jobs/GetPaginatedPrintJobs \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "page": 1,
  "page_size": 10,
  "printer_ids": [385],
  "status": ["cancelled", "finished"],
  "start_date": "2023-02-28"
}

Success response

{
  "status": true,
  "message": null,
  "data": [
    {
        "id": 549145,
        "uid": "7df103aa-b12c-4b33-8305-b55f91c11a4d",
        "status": "cancelled",
        "cancelReasonType": "5",
        "rating": -2,
        "filename": "Benchy.gcode",
        "startDate": "2023-02-28T21:05:50+00:00",
        "endDate": "2023-02-28T21:06:07+00:00",
        "user": 5933,
        "printer": 385,
        "filament": "{\"e0\": {\"usage\": 60}}",
        "filUsage": 60,
        "filUsageGram": 0,
        "currentPercentage": 48,
        "printTime": 17
    },
    ...
  ],
  "page_amount": 1
}

Get paginated data about ongoing or finished print jobs.

Request

POST /{id}/jobs/GetPaginatedPrintJobs

Parameter Type Required Description
page integer yes The page number to get.
page_size integer yes The number of items per page. (Between 1 and 100)
printer_types[] integer[] no Array of printer type ids to filter on.
printer_ids[] integer[] no Array of printer ids to filter on.
user_ids[] integer[] no Array of user ids to filter on.
accepted_statuses[] string[] no Array of job statuses to filter on. One of ongoing, cancelled, failed, done.
start_date string no The start date to filter on. In unix timestamp format. Can be set without end_date.
end_date string no The end date to filter on. In unix timestamp format. Can be set without start_date.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data array The jobs.
data[].id integer The job id.
data[].uid string The job uid.
data[].status string The job status. One of ongoing, cancelled, failed, done.
data[].cancelReasonType string The job cancel reason type.
data[].rating integer The job rating.
data[].filename string The job filename.
data[].startDate string The job start date.
data[].endDate string/null The job end date. Is null if the job is ongoing.
data[].user integer The user id of the user who started the job.
data[].printer integer The printer id that was used to print the job.
data[].filament string The filament usage. JSON encoded string with usage per extruder.
data[].filUsage integer The filament usage in mm.
data[].filUsageGram integer The filament usage in grams.
data[].currentPercentage integer The current percentage of the job.
page_amount integer The total number of pages for the given parameters.

User Management

Get Company Users

curl https://api.simplyprint.io/{id}/users/GetPaginatedUsers \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "page": 1,
    "page_size": 10,
    "approved": true,
    "search": "John Doe",
    "sort_id": 1,
    "sort_dir": "asc"
}

Success response

{
    "status": true,
    "message": null,
    "data": [
        {
            "id": 1234,
            "relation_id": 4321,
            "name": "John Doe",
            "email_confirmed": true,
            "email": "johndoe@example.com",
            "phone": "",
            "relation_created_at": "2022-07-28 23:30:14",
            "last_online": "2023-03-02 15:44:44",
            "approved_at": "2022-07-29 11:14:52",
            "org_account": false,
            "total_prints": 68,
            "rank": 185
        }
    ],
    "page_amount": 1
}
Required permissions
VIEW_USERS

Request

POST /{id}/users/GetPaginatedUsers

Parameter Type Required Description
page integer yes The page number to retrieve.
page_size integer yes The number of users to retrieve per page.
approved boolean no If true, only approved users will be returned. If false, only pending users will be returned.
Defaults to true
search string no A search string to filter the users by. Searches for name, email and phone number.
sort_id integer no Which field to sort by. See Sort IDs.
sort_dir string no The sort direction. Either asc or desc.

Sort IDs

ID Field
0 Name
1 Email
2 Rank id
3 Last online
4 Join date
5 Amount of prints

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data array An array of users.
data[].id integer The id of the user.
data[].relation_id integer The id of the user-company relation.
data[].name string The name of the user.
data[].email_confirmed boolean True if the user has confirmed their email address.
data[].email string The email address of the user.
data[].phone string The phone number of the user.
data[].relation_created_at string The date and time the user joined the company.
data[].last_online string The date and time the user was last online. Only present if user is approved
data[].approved_at string The date and time the user was approved. Only present if user is approved
data[].org_account boolean True if the user is an organization account. Only present if user is approved
data[].total_prints integer The total number of prints the user has made on this company. Only present if user is approved
data[].rank integer The id of the rank of the user. Only present if user is approved
page_amount integer The total number of pages. 
curl https://api.simplyprint.io/{id}/users/CreateInvitationLink \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "maxUses": 10
}

Success response

{
    "status": true,
    "message": null,
    "link": "https://simplyprint.io/accept_invitation/b3d9b5a0-5b5b-11e9-8d7c-2d3b9e84aafd"
}
Required permissions
INVITE_USERS

This endpoint creates an invitation link that can be used to invite new users to the company. Please note that links with unlimited uses expire at the end of the day.

Request

POST /{id}/users/CreateInvitationLink

Parameter Type Required Description
maxUses integer no The maximum number of times the link can be used. Specify 0 for unlimited uses.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
link string The invitation link.

Invite Users By Email

curl https://api.simplyprint.io/{id}/users/InviteSpecificUser \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "emails": [
        "test@example.com",
        "test2@example.com"
    ],
    "rank": 192,
    "lang": "en"
}

Success response

{
    "status": true,
    "message": null
}
Required permissions
INVITE_USERS

This endpoint invites one or more users to the company by email.

Request

POST /{id}/users/InviteSpecificUser

Parameter Type Required Description
emails string[] yes The emails of the users to invite.
rank integer no The rank id that the users should be assigned.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Accept or Deny Pending User

curl https://api.simplyprint.io/{id}/users/SetPendingUserState \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "relation_id": 1234,
    "approve": true,
    "notify": true
}

Success response

{
    "status": true,
    "message": null
}
Required permissions
INVITE_USERS

Request

POST /{id}/users/SetPendingUserState

Parameter Type Required Description
relation_id integer yes The id of the pending user-company relation.
approve boolean yes True to approve the user, false to deny.
notify boolean yes True to notify the user of the decision. Will send an email if the user has an email address.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Change User Rank

curl https://api.simplyprint.io/{id}/users/ChangeUserRank \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "relation_id": 1234,
    "rank_id": 192
}

Success response

{
    "status": true,
    "message": null
}

Request

POST /{id}/users/ChangeUserRank

Parameter Type Required Description
relation_id integer yes The id of the user-company relation.
rank_id integer yes The id of the rank to assign to the user.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Delete User

curl https://api.simplyprint.io/{id}/users/DeleteUser \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
    "user_id": 1234
}

Success response

{
    "status": true,
    "message": null
}
Required permissions
DELETE_USER

This endpoint deletes a user from the company. Use this endpoint with caution.

Request

POST /{id}/users/DeleteUser

Parameter Type Required Description
user_id integer yes The id of the user to delete.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Slicer

List Slicer Profiles

curl -X GET https://api.simplyprint.io/{id}/slicer/ListProfiles \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "profiles": [
    {
      "id": 785,
      "name": "Prusa profile",
      "for_printers": null,
      "org": true
    }
  ]
}

This endpoint returns a list overview of slicer profiles that the user has access to. Includes personal and company profiles.

Request

GET /{id}/slicer/ListProfiles

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.
profiles array An array of profile objects.
profiles.*.id integer The ID of the profile.
profiles.*.name string The name of the profile.
profiles.*.for_printers array The printers ids that this profile is made for.
profiles.*.org boolean True if this profile is owned by the company, and not by the user.

Get Slicer Profile

curl https://api.simplyprint.io/{id}/slicer/Get?id=1234 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "profile": {
    "id": 785,
    "name": "Prusa profile",
    "settings": {
      "sliceHeight": 0.2,
      "sliceFillSparse": 30,
      "sliceShells": 2,
      "sliceShellOrder": "in-out",
      "sliceTopLayers": 3,
      "sliceSolidLayers": 2,
      "sliceBottomLayers": 2,
      "outputFillMult": 1.1,
      "sliceFillAngle": 45,
      "outputShellMult": 1,
      "outputCoastDist": 0,
      "sliceSolidMinArea": 5,
      "sliceMinHeight": 0,
      "sliceLayerStart": "center",
      "sliceFillType": "hex",
      "sliceFillRate": 130,
      "outputSparseMult": 1.1,
      "sliceFillOverlap": 35,
      "firstSliceHeight": 0.2,
      "firstLayerLineMult": 100,
      "firstLayerFillRate": 35,
      "firstLayerRate": 10,
      "firstLayerPrintMult": 1,
      "firstLayerFanSpeed": 0,
      "sliceSupportOutline": 1,
      "sliceSupportAngle": 1,
      "sliceSupportDensity": 25,
      "sliceSupportSize": 6,
      "sliceSupportOffset": 0.4,
      "sliceSupportGap": 0,
      "sliceSupportSpan": 5,
      "sliceSupportArea": 0.25,
      "sliceSupportExtra": 0,
      "outputBrimCount": 0,
      "outputBrimOffset": 2,
      "outputRaftSpacing": 0.3,
      "outputSeekrate": 150,
      "outputFanLayer": 2,
      "fanSpeed": 100,
      "outputRetractDist": 1,
      "outputRetractSpeed": 100,
      "outputRetractDwell": 0,
      "outputRetractWipe": 2,
      "outputShortPoly": 50,
      "zHopDistance": 0,
      "antiBacklash": 0,
      "gcodePause": 0,
      "newLayerGcode": "",
      "firstLayerBeltLead": 0,
      "firstLayerBeltBump": 0,
      "firstLayerFlatten": 0,
      "firstLayerBrimIn": 0,
      "sliceSupportEnable": 0,
      "outputRaft": 0,
      "outputLayerRetract": 0
    },
    "for_printers": null,
    "org": true
  }
}

This endpoint can be used to get a slicer profile by its ID. This includes the settings of the profile.

Request

GET /{id}/printers/Delete

Parameter Type Required Description
id integer yes The id of the profile to fetch.

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.
profile object The profile object.
profile.id integer The ID of the profile.
profile.name string The name of the profile.
profile.settings object The settings of the profile.
profile.for_printers array The printers ids that this profile is made for.
profile.org boolean True if this profile is owned by the company, and not by the user.

Save or Create Slicer Profile

curl https://api.simplyprint.io/{id}/slicer/SaveProfile?id=1234 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

TODO

Delete Slicer Profile

curl -X GET https://api.simplyprint.io/{id}/slicer/DeleteProfile?id=1234 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null
}
Required permissions Description
SLICER_ORG_PROFILES If the profile is owned by the company.

This endpoint can be used to delete a slicer profile by its ID.

Request

GET /{id}/printers/Delete

Parameter Type Required Description
id integer yes The id of the profile to delete.

Response

Field Type Description
status boolean True if the request was successful.
message string Error message if status is false.

Tags

Create or Update Custom Tag

curl -X POST https://api.simplyprint.io/{id}/tags/Create \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Request body

{
  "name": "My Custom Tag",
  "badge": "success",
}

Success response

{
  "status": true,
  "message": null,
  "id": 2,
  "tags": [
    {
      "id": 1,
      "name": "A tag",
      "badge": "primary",
      "used_by": {
        "printers": 1,
        "printer_groups": 0,
        "files": 2,
        "queue_items": 4,
      }
    },
    {
      "id": 2,
      "name": "My Custom Tag",
      "badge": "success",
    }
  ]
}
Required permissions
EDIT_TAGS

This endpoint creates or updates a custom tag.

Request

POST /{id}/tags/Create

Parameter Type Required Description
id integer no ID of the tag to update. Leave empty to create a new tag.
name string yes Name of the tag.
badge string yes Color of the tag. Please refer to the Colors section for a list of available colors.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.
id integer ID of the created or updated tag.
tags array Array of all tags.
tags.*.id integer ID of the tag.
tags.*.name string Name of the tag.
tags.*.badge string Color of the tag.
tags.*.used_by object Only present if the tag is used on any printers, printer groups, files or queue items.
tags.*.used_by.printers integer Number of printers the tag is used on.
tags.*.used_by.printer_groups integer Number of printer groups the tag is used on.
tags.*.used_by.files integer Number of files the tag is used on.
tags.*.used_by.queue_items integer Number of queue items the tag is used on.

Get Custom Tag(s)

Get a single tag

curl https://api.simplyprint.io/{id}/tags/Get?id=2 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "tag": {
    "id": 2,
    "name": "My Custom Tag",
    "badge": "success",
  }
}

Get all tags

curl https://api.simplyprint.io/{id}/tags/Get \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "tags": [
    {
      "id": 1,
      "name": "A tag",
      "badge": "primary",
      "used_by": {
        "printers": 1,
        "printer_groups": 0,
        "files": 2,
        "queue_items": 4,
      }
    },
    {
      "id": 2,
      "name": "My Custom Tag",
      "badge": "success",
    }
  ]
}

This endpoint gets a single tag or all tags.

Request

GET /{id}/tags/Get

Parameter Type Required Description
id integer no ID of the tag to get. Leave empty to get all tags.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.
tag object Only present if id is set.
tag.id integer ID of the tag.
tag.name string Name of the tag.
tag.badge string Color of the tag.
tag.used_by object Only present if the tag is used on any printers, printer groups, files or queue items.
tags array Only present if id is not set. Array of all tags.
tags.* object Tag data like in the tag object above.

Delete Custom Tag

curl https://api.simplyprint.io/{id}/tags/Delete?id=2 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "tags": [
    {
      "id": 1,
      "name": "A tag",
      "badge": "primary",
      "used_by": {
        "printers": 1,
        "printer_groups": 0,
        "files": 2,
        "queue_items": 4,
      }
    }
  ]
}
Required permissions
EDIT_TAGS

This endpoint deletes a custom tag.

Request

GET /{id}/tags/Delete

Parameter Type Required Description
id integer yes ID of the tag to delete.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.
tags array Array of all tags.

Assign Nozzle Size Tag

curl -X POST https://api.simplyprint.io/{id}/tags/Assign \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \

Request body

{
  "type": 1,
  "id": 2315,
  "edited": "nozzle",
  "nozzle": 0.4
}

Success response

{
  "status": true,
  "message": null,
}

This endpoint assigns a nozzle size tag to a printer, printer group, file or queue item.

Please note that to assign a tag to a printer, you need the EDIT_PRINTER permission.

Request

POST /{id}/tags/Assign

Parameter Type Required Description
type integer yes What to assign the tag to. 1 for printer, 2 for printer group, 3 for file, 4 for queue item.
id integer/string yes ID of the printer, printer group, file or queue item to assign the tag to.
edited string yes Set to nozzle to assign a nozzle size tag.
nozzle float yes Nozzle size to assign in millimeters.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Assign Material Tag

curl -X POST https://api.simplyprint.io/{id}/tags/Assign \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \

Request body

{
  "type": 1,
  "id": 2315,
  "edited": "material",
  "material": [
    {
      "ext": 0,
      "type": 412,
      "hex": "#ff0000",
      "color": "Red"
    }
  ]
}

Success response

{
  "status": true,
  "message": null,
}

This endpoint assigns a material tag to a printer, printer group, file or queue item.

Please note that to assign a tag to a printer, you need the EDIT_PRINTER permission.

Request

POST /{id}/tags/Assign

Parameter Type Required Description
type integer yes What to assign the tag to. 1 for printer, 2 for printer group, 3 for file, 4 for queue item.
id integer/string yes ID of the printer, printer group, file or queue item to assign the tag to.
edited string yes Set to material to assign a material tag.
material array yes Array of materials to assign.
material.*.ext integer yes Material extruder to assign the tag to. (zero-indexed)
material.*.type integer yes Material type id to assign.
material.*.hex string yes Material color hex code.
material.*.color string yes Material color name.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Assign Custom Tag

curl -X POST https://api.simplyprint.io/{id}/tags/Assign \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \

Request body

{
  "type": 1,
  "id": 2315,
  "edited": "custom",
  "tag_id": 1
}

Success response

{
  "status": true,
  "message": null,
}

This endpoint assigns a custom tag to a printer, printer group, file or queue item.

Please note that to assign a tag to a printer, you need the EDIT_PRINTER permission.

Request

POST /{id}/tags/Assign

Parameter Type Required Description
type integer yes What to assign the tag to. 1 for printer, 2 for printer group, 3 for file, 4 for queue item.
id integer/string yes ID of the printer, printer group, file or queue item to assign the tag to.
edited string yes Set to custom to assign a custom tag.
tag_id integer yes ID of the custom tag to assign.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Detach Custom Tag

curl -X POST https://api.simplyprint.io/{id}/tags/Detach \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \

Request body

{
  "type": 1,
  "id": 2315,
  "tag_id": 1
}

Success response

{
  "status": true,
  "message": null,
}

This endpoint detaches a custom tag from a printer, printer group, file or queue item.

Please note that to detach a tag from a printer, you need the EDIT_PRINTER permission.

Request

POST /{id}/tags/Detach

Parameter Type Required Description
type integer yes What to detach the tag from. 1 for printer, 2 for printer group, 3 for file, 4 for queue item.
id integer/string yes ID of the printer, printer group, file or queue item to detach the tag from.
tag_id integer yes ID of the custom tag to detach.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Success message or error message if status is false.

Colors

Color Name Preview
Blue primary Primary
Purple secondary Secondary
Green success Success
Red danger Danger
Yellow warning Warning
Turquoise info Info
Light grey light Light
Dark dark Dark

Permissions

Permission Description
PRINTER_EDIT "Allow to create, edit and delete printers"
CREATE_FILAMENT "Allow creating, editing and deleting filament spools"
CHANGE_FILAMENT "Allow change of filament"
PRINT_QUEUE_REMOVE_ALL "Allow deletion of other user's print queue items"
ORG_RANK_MANAGEMENT "Allow to create, edit, delete and change order of user groups"
VIEW_USERS "Allow overview of users in organization"
INVITE_USERS "Allow invite of other users"
DELETE_USER "Allow delete users"
SLICER_ORG_PROFILES "Allow to create and edit organisation slicer profiles"
EDIT_TAGS "Allow user to create, update and delete tags"

Errors

The SimplyPrint API uses the following HTTP error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Request not allowed.
404 Not Found -- Endpoint not found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The endpoint requested has been removed from our servers.
429 Too Many Requests -- You're requesting too much - slow down
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Error Response

Error response example:

{
  "status": false,
  "message": "No API key provided, or not logged in"
}

When an error occurs, the API will return a JSON object with the following fields:

Field Description Type
status The status of the request Boolean
message A message describing the error String
cURL