NAV
cURL

Getting Started

Welcome to the SimplyPrint API!

This documentation goes through authenticating and how to use the API.

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.

Gaining access to the API

There are two ways to gain access to the SimplyPrint API:

  1. Using an API key (recommended)
    • This is the recommended method for most users. This method requires a SimplyPrint account and an API key.
  2. Using OAuth2
    • This method is only available for approved integrations. You can use OAuth2 to access SimplyPrint API endpoints on behalf of a user.

To get an API key you'll need a SimplyPrint account that is either a member of an organization, or have 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.

Using the 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.

Using OAuth2

SimplyPrint supports OAuth2 logins for all users, regardless of their subscription, for approved integrations such as the Cura slicer integration.

The OAuth2 method can be used to link a user's SimplyPrint account with a third party platform/software, and use the SimplyPrint API on behalf of the user.

To obtain OAuth2 access, you must be added as an OAuth2 provider by SimplyPrint. To request this, please fill out the OAuth2 Client Request Form.

Once you have been added as an OAuth2 provider, you can use the following documentation to implement OAuth2 in your application.

Authorizing your application

For users to grant your application access to their SimplyPrint account, you must first redirect them to the SimplyPrint OAuth2 authorization page. You can do this by redirecting the user to the following URL:

https://api.simplyprint.io/oauth2/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}

The following parameters can be supplied as query parameters in the URL:

Parameter Type Required Description
client_id string yes The client ID of your OAuth2 application
redirect_uri string yes The redirect URI of your OAuth2 application
scope string yes The scope of the OAuth2 access token. This can be a +-separated list of scopes.
response_type string yes This must be set to code
state string no The value of this parameter will be returned to your application when the user is redirected back

Once the user has granted access to your application, they will be redirected to {redirect_uri}?code={code}&state={state}. The code parameter is the authorization code that you will use to obtain an access token. The state parameter will only be returned if you specified a state parameter in the authorization URL.

Obtaining an access token

Obtaining an access token

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

Request body

{
  "grant_type": "authorization_code",
  "client_id": "{client_id}",
  "client_secret": "{client_secret}",
  "code": "{code}",
  "redirect_uri": "{redirect_uri}"
}

Success response

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "{access_token}",
  "refresh_token": "{refresh_token}"
}

Now that you have a code parameter, you can use it to obtain an access token. To do this, you must make a POST request to the following URL:

https://api.simplyprint.io/oauth2/Token

This will return an access token that you can use to make requests to the SimplyPrint API on behalf of the user.

This access token will expire after 1 hour. Once it expires, you can use the refresh_token parameter to obtain a new access token. To do this, you must make a POST request to the same URL as above, but with the following request parameters:

Parameter Type Description
grant_type string This must be set to refresh_token
client_id string The client ID of your application
client_secret string The client secret of your application
refresh_token string The refresh token that was returned when you obtained the access token

To refresh your access token, you can make a POST request to the same URL as above, but with the following request parameters:

Parameter Type Description
grant_type string This must be set to refresh_token
client_id string The client ID of your application
client_secret string The client secret of your application
refresh_token string The refresh token that was returned when you obtained the access token

This will return a new access token that you can use to make requests to the SimplyPrint API on behalf of the user.

Testing your access token

Testing your access token

curl https://api.simplyprint.io/oauth2/TokenInfo \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access_token}'

Success response

{
  "status": true,
  "message": null,
  "user": {
    "id": 112,
    "name": "John Doe",
    "email": "john@doe.com",
  },
  "company": {
    "id": 123,
    "name": "My Company"
  },
  "scopes": [
    ...
  ],
  "expires_at": 1706292803
}

To test your access token, you can make a GET request to the following URL:

https://api.simplyprint.io/oauth2/TokenInfo

This endpoint returns the following information:

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
user object User object.
user.id integer User ID.
user.name string User name. This is only returned if the user.read scope is included in the access token.
user.email string User email. This is only returned if the user.read scope is included in the access token.
company object Company object.
company.id integer Company ID.
company.name string Company name.
scopes array Array of scopes that are included in the access token.
expires_at integer The unix timestamp of when the access token expires.

The company id is especially important, as you will need to use this in the base URL for all requests to the SimplyPrint API.

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/null Tags for printer; custom tags, static material data & nozzle size

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,
      "cost": [
        {
          "estimate": false,
          "total_cost": 1006.76,
          "lines": [
            {
              "id": 1,
              "label": "HIPS Material usage",
              "cost": 0.05
            },
            {
              "id": 2,
              "label": "Material markup",
              "cost": 0.03
            },
            {
              "id": 3,
              "label": "Machine run time cost",
              "cost": 6.67
            },
            {
              "id": 4,
              "label": "Energy cost",
              "cost": 0.01
            },
            {
              "id": 5,
              "label": "Labor cost",
              "cost": 1000
            }
          ]
        }
      ]
    }
  ],
  "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, a file_id 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.
multi_queue object no A map of queue item ID to an array of printer IDs. For example {638: [12645, 12646]}.
next_queue_item boolean no If true, the next queue item will be printed.
This requires the Print Farm plan
file_id string no File ID from API Files - used to start a file without adding it as a queue item or user file.
mms_map object no A map of printer ids to a map of the extruder specified in the gcode, and the printer extruder index.
custom_fields array no An array with custom fields to assign to the print job. Each custom field consists of {customFieldId: string, value: <value>} where the <value> is a Custom Field Submission Value.

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.
files[].cost object[] nullable
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.

Send raw gcode

curl https://api.simplyprint.io/{id}/printers/actions/SendGcode?pid=1234 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "gcode": ["G28 XY"]
  }'

Success response

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

POST /{id}/printers/actions/SendGcode

Request Parameters

Parameter Type Description
pid integer[] The ID(s) of the printer(s) to send the gcode to.

Request body

Parameter Type Required Description
gcode string[] yes Array of gcode commands to send to the printer.

Response

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

List 1-Click printers

Required permission
print_queue 
curl https://api.simplyprint.io/{id}/printers/OneClickPrint?pIds=1234,1235 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "bedsMustBeCleared": true,
  "autoAddAvailable": true,
  "settings": {
    ...
  },
  "canEditSettings": true,
  "hasQueue": true,
  "custom_fields": [
    ...
  ],
  "queue": [
    ...
  ]
}

GET /{id}/printers/OneClickPrint?pid=1234,1235

Query parameters

Parameter Type Required Description
pid integer[] yes Printers you want to retrieve data about

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
bedsMustBeCleared boolean true if beds must be cleared before printing.
autoAddAvailable boolean true if auto-discover printers is available.
settings object Queue auto-start settings.
canEditSettings boolean true if the user can edit settings.
hasQueue boolean true if the company has a print queue.
custom_fields array Array of custom fields for the print queue.
queue array Array of next items in the print queue.

AutoPrint enable / disable

Required permission
autoprint_manage 
curl https://api.simplyprint.io/{id}/printers/autoprint/SetEnabled \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "on": true
  }'

Success response

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

POST /{id}/printers/autoprint/SetEnabled

Request body

Parameter Type Required Description
on boolean yes Set to true to enable autoprint, or false to disable it.

Response

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

AutoPrint check state

Required permission
autoprint_manage 
curl https://api.simplyprint.io/{id}/printers/autoprint/CheckState \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "printers": [
    {
      ...
    }
  ]
}

GET /{id}/printers/autoprint/CheckState

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
printers array Array of printers along with their AutoPrint status.
printers[].printer integer The printer id.
printers[].ready boolean Whether the printer is ready.
printers[].issues array An array of issues with the printer.
printers[].state object The state of the printer.
printers[].state.awaitingBedCool boolean True if the printer is awaiting the bed to cool down.
printers[].state.awaitingSecondsPass boolean True if the printer is awaiting a specified number of seconds to pass.
printers[].state.awaitingManualClear boolean True if the printer is awaiting manual clearance.
printers[].state.maxCyclesReached boolean True if the printer has reached the maximum number of print cycles.
printers[].state.waitingForSystem boolean True if the printer is waiting for the system.
printers[].state.awaitingMatchingQueueItem boolean True if the printer is awaiting a matching queue item.
printers[].nextItem object/null The next queue item formatted for the printer.

AutoPrint get settings

Required permission
autoprint_manage 
curl https://api.simplyprint.io/{id}/printers/autoprint/GetAutoPrintSettings \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "gcode": "...",
  "printer_settings": {
    ...
  },
  "printer_has_settings": true,
  "account_settings": {
    ...
  },
  "account_has_settings": true,
  "queue_match_settings": {
    ...
  },
  "can_macro": true
}

GET /{id}/printers/autoprint/GetAutoPrintSettings

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
gcode string G-code for clearing the auto print settings.
printer_settings object The auto print settings for the printer.
printer_has_settings boolean true if the printer has auto print settings.
account_settings object The auto print settings for the account.
account_has_settings boolean true if the account has auto print settings.
queue_match_settings object The queue match criteria settings for the account.
can_macro boolean true if the user has permission to manage G-code profiles for the company.

AutoPrint save settings

Required permission
autoprint_manage 
curl https://api.simplyprint.io/{id}/printers/autoprint/SaveAutoPrintSettings \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "useDefault": true,
    "saveAsDefault": false,
    "bedReleaseTemp": 60,
    "autoReleaseTime": 3600,
    "maxPrints": 100,
    "ackNoGcode": true,
    "method": "loop"
  }'

Success response

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

POST /{id}/printers/autoprint/SaveAutoPrintSettings

Request Body

Parameter Type Description
useDefault boolean true to use company defaults, false to use custom settings.
saveAsDefault boolean true to save the settings as company defaults.
bedReleaseTemp integer Temperature at which the bed releases the print.
autoReleaseTime integer Time in seconds after which the print is automatically released.
maxPrints integer Maximum number of prints before requiring manual intervention.
ackNoGcode boolean true to acknowledge no G-code is required.
method string Method to use for auto print settings. One of loop, jobox, 3dque, belt, pushoff

Response

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

AutoPrint get gcode templates

Required permission
autoprint_manage 
curl https://api.simplyprint.io/{id}/printers/autoprint/GetGcodeTemplates \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "methods": [
    {
      "name": "loop",
      "gcode": "..."
    },
    {
      "name": "jobox",
      "gcode": "..."
    },
    {
      "name": "3dque",
      "gcode": "..."
    },
    {
      "name": "belt",
      "gcode": "..."
    },
    {
      "name": "pushoff",
      "gcode": "..."
    }
  ]
}

GET /{id}/printers/autoprint/GetGcodeTemplates

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
methods array Array of G-code templates for different methods.
methods[].name string Name of the method.
methods[].gcode string G-code template for the method.

AutoPrint set cleared beds amount

Required permission
autoprint_manage 
curl https://api.simplyprint.io/{id}/printers/autoprint/SetClearedBedsAmount \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 10
  }'

Success response

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

POST /{id}/printers/autoprint/SetClearedBedsAmount

Request Body

Parameter Type Description
pid integer[] The ID(s) of the printer(s) to set the cleared beds amount for.
amount integer The number of cleared beds to set for the printer(s). Must be between 0 and 100000.

Response

Parameter 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,
  "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 in your account-defined currency (changed in account settings).
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.

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,
      "autoprint": false,
      "outsideSystem": false,
      "printer": 385,
      "filament": "{\"e0\": {\"usage\": 60}}",
      "filUsage": 60,
      "filUsageGram": 0,
      "currentPercentage": 48,
      "printTime": 17,
      "cost": {
        "estimate": false,
        "total_cost": 150,
        "lines": [
          {
            "id": 1,
            "label": "Material usage (account default)",
            "cost": 0.02
          },
          {
            "id": 2,
            "label": "Material markup",
            "cost": null
          },
          {
            "id": 3,
            "label": "Machine run time cost",
            "cost": null
          },
          {
            "id": 4,
            "label": "Energy cost",
            "cost": null
          },
          {
            "id": 5,
            "label": "Labor cost",
            "cost": 1000
          }
        ]
      },
      "queueItem": {
        "id": 1234,
        "user": 51,
        "queueNum": 3
      },
      "customFields": [
        {
          "id": "student_id",
          "value": {
            "string": "1234567890"
          }
        }
      ]
    },
    ...
  ],
  "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, finished.
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. Note that done is the same as finished
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/null The user id of the user who started the job.
data[].autoprint boolean If the job was started automatically using the Auto-print feature
data[].outsideSystem boolean If the job was started outside SimplyPrint, via SD card, OctoPrint, Mailsail, Fluidd or else how
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.
data[].cost object/null Potential calculated cost of job.
data[].queueItem object/null The queue item that was used to start the job. Please note that this is only shown if you have access to view the Print Queue.
data[].queueItem.id integer The id of the queue item that was used to start the job.
data[].queueItem.user integer The user id of the user who created the queue item.
data[].queueItem.queueNum integer The queue number of the queue item.
page_amount integer The total number of pages for the given parameters.

Get details

curl https://api.simplyprint.io/{id}/jobs/GetDetails \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "id": "job_id"
  }'

Success response

{
  "status": true,
  "message": null,
  "job": {
    "id": 123,
    "filament": [
      ...
    ],
    "pauses": [
      ...
    ],
    "currentTime": 1697040000,
    "pictures": [
      ...
    ],
    "notificationsSent": [
      ...
    ],
    "cost": 12.34,
    "customFields": {
      ...
    },
    "ended": 3600,
    "failedReason": "string",
    "cancelInfo": {
      "reason": "string",
      "comment": "string",
      "by": "string",
      "byOther": 1
    },
    "analysis": {
      ...
    },
    "notifications": {
      ...
    },
    "outsideSystem": true,
    "rating": 5,
    "started": 7200,
    "created": 10800,
    "state": "string",
    "file": "filename.gcode",
    "percentage": 50,
    "time": 1800,
    "canPreview": true,
    "layer": 10,
    "ai": [
      0.1,
      0.2,
      0.3
    ],
    "printer": {
      "id": 456,
      "name": "Printer Name",
      "extruders": 2,
      "image": "https://cdn.simplyprint.io/prints/images/printer_image.jpg",
      "deleted": 1
    },
    "spools": [
      ...
    ]
  }
}

GET /{id}/jobs/GetDetails?id={job_id}

Request Body

Parameter Type Description
id string The job UID.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
job object Details about the print job.
job.id integer Unique identifier for the job.
job.filament array Array of filament data.
job.pauses array Array of pause history.
job.currentTime integer Current timestamp.
job.pictures array Array of pictures related to the job.
job.notificationsSent array Array of notifications sent.
job.cost float Cost of the print job.
job.customFields object Custom fields for the job.
job.ended integer Time since the job ended.
job.failedReason string Reason for job failure, if any.
job.cancelInfo object Information about job cancellation.
job.analysis object G-code analysis data.
job.notifications object Notification data.
job.outsideSystem boolean true if the job is outside the system.
job.rating integer Rating of the job.
job.started integer Time since the job started.
job.created integer Time since the job was created.
job.state string Current state of the job.
job.file string Original filename of the job.
job.percentage integer Current completion percentage.
job.time integer Time left or time since the job ended.
job.canPreview boolean true if the job can be previewed.
job.layer integer Current layer of the print.
job.ai array Array of AI detection values.
job.printer object Details about the printer.
job.spools array Array of spool data.

API Files

The base URL for the SimplyPrint Files API is https://files.simplyprint.io/{id}/. Use the exact same authentication as the normal api endpoint. It is very important you ensure you send files with the correct file extension. The API will not be able to determine the file type based on the content.

Upload a file using the API

POST /{id}/files/Upload

Example request to upload a file less than 100MB

curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \
    -H 'accept: application/json' \
    -H "X-API-KEY: {API_KEY}" \
    -F "file=@/path/to/file.gcode"

Success response

{
  "status": true,
  "message": null,
  "file": {
    "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd",
    "name": "file.gcode",
    "size": 13439
  }
}

Multiple parts for a single file larger than 100MB. The first filename is the filename of the entire file.

curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \
    -H 'accept: application/json' \
    -H "X-API-KEY: {API_KEY}" \
    -F "file=@/path/to/part1.3mf"
    -F "totalSize=3352316"

Success response with continueToken

{
  "status": true,
  "message": null,
  "continueToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJ0eXBlIjoiYWN0ao9uX3Rva2VuIiwiYWN0aW9uIjoiZmlsZV9jb250aW51ZV91cGxvYWQiLCJ1c2VyIjo2OTc2LCJjb21wYW55IjoyLCJkYXRhIja7ImJ1Y2tldEhhc2giOiI0MGQ2MzgwNmQwYWUxODhkNjc5YzY0NjA0M2RiYjUxMTc0NTViNTc1NjNlODEzZDc2MGRjMTJkMzVaYjdmY2Y0IiwidG90YWxTaXplIjoxNjc2MTU4NH0sImlhdCI6MTcyNTU2MjEzMywiZXhwIjoxNzI1NjQ4NTMzfQ.9qyNyx9A4Ox_6GrFSxXpxlpLcAKaSr8ln84X3yuWdhT_2O3L8-lGWaXAbQk9VvR-3pu1-a9p40amnt6Fghy49InjzCfNMRp-6-Ft_uMRf6PbmcCCrksvRxNP38ImoXy6"
}

Continue uploading the file (send next part with only the continueToken)

curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \
    -H 'accept: application/json' \
    -H "X-API-KEY: {API_KEY}" \
    -F "continueToken=eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJ0eXBlIjoiYWN0ao9uX3Rva2VuIiwiYWN0aW9uIjoiZmlsZV9jb250aW51ZV91cGxvYWQiLCJ1c2VyIjo2OTc2LCJjb21wYW55IjoyLCJkYXRhIja7ImJ1Y2tldEhhc2giOiI0MGQ2MzgwNmQwYWUxODhkNjc5YzY0NjA0M2RiYjUxMTc0NTViNTc1NjNlODEzZDc2MGRjMTJkMzVaYjdmY2Y0IiwidG90YWxTaXplIjoxNjc2MTU4NH0sImlhdCI6MTcyNTU2MjEzMywiZXhwIjoxNzI1NjQ4NTMzfQ.9qyNyx9A4Ox_6GrFSxXpxlpLcAKaSr8ln84X3yuWdhT_2O3L8-lGWaXAbQk9VvR-3pu1-a9p40amnt6Fghy49InjzCfNMRp-6-Ft_uMRf6PbmcCCrksvRxNP38ImoXy6" \
    -F "file=@/path/to/part2.3mf"

Sucessful final response as we ensured to only send exactly the total size of the file.

{
  "status": true,
  "message": null,
  "file": {
    "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd",
    "name": "part1.3mf",
    "size": 3352316
  }
}

Request

Parameter Type Required Description
file file yes Uploaded file (Max 100mb)
continueToken string no Optional token you'll get if you need to continue the upload for files greater than 100MB.
totalSize integer no Send this if you want a continueToken, by providing the total size of the entire file you want to upload

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
continueToken string For every subsequent request that still has some pending size based on the total size this will be returned instead of the file.
file.* object Final file object after entire file has been uploaded
file.id string The API File ID you'll need to use other SimplyPrint APIs
file.name string Name used to reference the file
file.size int Total size of uploaded file

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
fileId string no Optional File ID from API File - use this to add a file uploaded via the API.
tags object no Tags to assign. Only send nozzle body, material body or custom body, without type, id or edited
for_printers array no An array of printer ids to assign the queue item to.
for_models array no An array of printer model ids to assign the queue item to.
for_groups array no An array of group ids to assign the queue item to.
custom_fields array no An array with custom fields to assign to the queue item. Each custom field consists of {customFieldId: string, value: <value>} where the <value> is a Custom Field Submission Value.

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,
        "customFields": [
          {
            "id": "student_id",
            "value": {
              "string": "1234567890"
            }
          }
        ]
      }
    ]
  }
}

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 item

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

Success response

{
  "status": true,
  "message": null,
  "queue": {
    "id": 51293,
    "index": 1,
    "filename": "benchy.gcode",
    "note": null,
    "model": false,
    "printable": true,
    "type": "printable",
    "zipPrintable": false,
    "zipNoModel": false,
    "left": 1,
    "printed": 0,
    "filesystem_id": "c00489ef361771ac098b5a60e6740757",
    "group": 123,
    "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
    },
    "tags": {
      "nozzle": 0.6,
      "material": [
        {
          "ext": 0,
          "type": 123,
          "color": "Green",
          "hex": "#4CAF50"
        }
      ],
      "custom": [
        1,
        2,
        3
      ]
    }
  }
}
Required permissions
print_queue

This endpoint returns the queue item with the specified id.

Request

`GET /{id}/queue/GetItem

Parameter Type Required Description
id integer yes The queue item id to get details for.

Response

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

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": 123,
        "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
          ]
        },
        "customFields": [
          {
            "id": "student_id",
            "value": {
              "string": "1234567890"
            }
          }
        ]
      }
    ]
  },
  "groups": [
    {
      "id": 123,
      "name": "Group 1",
      "virtual": false,
      "extensions": [
        "gcode",
        "gco",
        "stl"
      ],
      "sort_order": 0
    },
    ...
  ]
}
Required permissions
print_queue

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.
groups boolean no Attaches a list of print queue groups to the response. Note: this argument does not take a value.

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/null Optional note text.
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/null Tags for queue item; custom tags, static material data & nozzle size
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/null UTC date that the item was finished.
queue.done_items[].expires UTC date/null UTC date that the item expires and is removed from the platform.
groups array If groups GET is set, an array of print queue groups.
groups[].id integer The group id.
groups[].name string The group name.
groups[].virtual boolean Whether the group is a virtual queue group.
groups[].extensions array/null An array of file extensions that are allowed in the group.
groups[].sort_order integer The sort index of the group.

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
}
Required permissions
print_queue

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
}
Required permissions
print_queue

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
}
Required permissions
print_queue
reorder_queue
queue_see_others

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

Revive item

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

Success response

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

POST /{id}/queue/ReviveItem

Request Parameters

Parameter Type Description
job integer The ID of the job to revive.

Response

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

Get groups

Required permissions
print_queue 
curl https://api.simplyprint.io/{id}/queue/groups/Get \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "list": [
    {
      "id": 1,
      "name": "Queue Group 1",
      "virtual": false,
      "extensions": [
        "gcode",
        "bgcode"
      ],
      "sort_order": 1
    }
  ]
}

GET /{id}/queue/groups/Get

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
list array Array of print queue groups.
list[].id integer Unique identifier for the group.
list[].name string Name of the group.
list[].virtual boolean Whether the group is a virtual queue group.
list[].extensions array An array of file extensions that are allowed in the group. (without punctuation)
list[].sort_order integer The sort order of the group.
list[].for object For which printers, models and groups this queue item is for.

Save group

Required permissions
print_queue
queue_groups 
curl https://api.simplyprint.io/{id}/queue/groups/Save \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "id": 123,
    "name": "New Queue Group",
    "accepted_extensions": ["gcode", "bgcode"],
    "virtual_only": false,
    "for_printers": "1,2,3",
    "for_models": "4,5,6",
    "for_groups": "7,8,9"
  }'

Success response

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

POST /{id}/queue/groups/Save

Request Body

Parameter Type Description
id integer The ID of the group to update (optional for creating a new group).
name string The name of the queue group.
accepted_extensions array List of accepted file extensions.
virtual_only boolean Whether the group is virtual only.
for_printers string Comma-separated list of printer IDs.
for_models string Comma-separated list of printer model IDs.
for_groups string Comma-separated list of printer group IDs.

Response

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

Delete group

Required permissions
print_queue
queue_groups 
curl https://api.simplyprint.io/{id}/queue/groups/Delete?id=123 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \

Success response

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

POST /{id}/queue/groups/Delete

Request Parameters

Parameter Type Description
id integer The ID of the group to delete.

Request Body

Parameter Type Description
move_to integer The ID of the group to move items to. Defaults to any other group.

Response

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

Set group order

Required permissions
queue_groups
reorder_queue 
curl https://api.simplyprint.io/{id}/queue/groups/SetOrder?queue_group=123 \
  -X POST \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "from": 1,
    "to": 2
  }'

Success response

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

POST /{id}/queue/groups/SetOrder

Request Parameters

Parameter Type Description
queue_group integer The ID of the queue group.

Request Body

Parameter Type Description
to integer The new sorting order of the group.

Response

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

Printer Groups

Get groups

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

Success response

{
  "status": true,
  "message": null,
  "groups": [
    {
      "id": 1,
      "name": "Group 1"
    },
    {
      "id": 2,
      "name": "Group 2"
    }
  ]
}

GET /{id}/groups/Get

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
groups array Array of printer groups.
groups[].id integer Unique identifier for the group.
groups[].name string Name of the group.

Create group

curl https://api.simplyprint.io/{id}/groups/Create \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "name": "New Group Name"
  }'

Success response

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

POST /{id}/groups/Create

Required permissions
printer_edit

Request Body

Parameter Type Description
name string The name of the new group.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
id integer Unique identifier for the new group.

Update group

curl https://api.simplyprint.io/{id}/groups/Update?group=123 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "name": "Updated Group Name"
  }'

Success response

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

POST /{id}/groups/Update

Required permissions
printer_edit

Request Parameters

Parameter Type Description
group integer The ID of the group to update.

Request Body

Parameter Type Description
name string The new name for the group.

Response

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

Delete group

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

Success response

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

POST /{id}/groups/Delete

Required permissions
printer_edit

Request Parameters

Parameter Type Description
group integer The ID of the group to delete.

Response

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

Arrange groups

curl https://api.simplyprint.io/{id}/groups/Arrange?pid=1234&group=123 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "from": 1,
    "to": 2
  }'

Success response

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

POST /{id}/groups/Arrange

Request Parameters

Parameter Type Description
pid integer The ID of the printer to arrange.
group integer The ID of the group to move to.

Request Body

Parameter Type Description
from integer The current position of the printer.
to integer The new position of the printer.

Response

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

Files

Add an API File to files

POST {id}/files/Upload?folder={folder}

Parameter Type Required Description
folder (GET) integer no Folder ID to get files for. Defaults to 0 (root folder)
fileId (POST) string yes File ID from API Files

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
id string User file ID of newly added file 
curl -X POST https://api.simplyprint.io/{id}/files/Upload?folder=5290 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -F 'fileId=43aaad56548c959f655d0524027b726a7514493ec8436f4942f876bb07eab731'

Success Response

{
  "status": true,
  "message": null,
  "id": "6f7d79212f384c6b8eae2811c37d9338"
}

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": "printable",
      "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
        ]
      },
      "cost": {
        "estimate": false,
        "total_cost": 150,
        "lines": [
          {
            "id": 1,
            "label": "Material usage (account default)",
            "cost": 0.02
          },
          {
            "id": 2,
            "label": "Material markup",
            "cost": null
          },
          {
            "id": 3,
            "label": "Machine run time cost",
            "cost": null
          },
          {
            "id": 4,
            "label": "Energy cost",
            "cost": null
          },
          {
            "id": 5,
            "label": "Labor cost",
            "cost": 1000
          }
        ]
      }
    }
  ],
  "customFields": [
    {
      "id": "student_id",
      "value": {
        "string": "1234567890"
      }
    }
  ],
  "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.
pid integer no For print cost calculation, if you want the files to use the material of a printer, request with the ID of the printer - don't include the pid argument otherwise

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

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

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,
      "teacher": false,
      "classes": [
        1234,
        5678
      ]
    }
  ],
  "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 string no Which field to sort by. Options: name, contact, rank, lastOnline, added, totalPrints.
sort_dir string no The sort direction. Either asc or desc.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
page_amount integer The total number of pages.
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[].sso boolean True if the user was created via SSO.
Approved users only
data[].last_online string The date and time the user was last online.
data[].approved_at string The date and time the user was approved.
data[].org_account boolean True if the user is an organization account.
data[].total_prints integer The total number of prints the user has made on this company.
data[].rank integer The id of the rank of the user.
Schools only
data[].teacher boolean True if the user is a teacher.
data[].classes array An array of class IDs the user is a member of. 
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.

Set Teacher

POST /{id}/users/SetIsTeacher

Example request

curl -X POST \
https://api.simplyprint.io/{id}/users/SetIsTeacher \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {API_KEY}' \
-d '{"relation_id": 123, "is_teacher": true}'

Example response

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

Request

Parameter Type Required Description
relation_id integer yes The ID of the company-user relation to update.
is_teacher boolean yes Set to true to mark the user as a teacher or false otherwise.

Response

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

Schools

List classes

GET /{id}/account/settings/school/classes/GetClasses

Example request

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

Example response

{
  "status": true,
  "message": null,
  "objects": {
    "classes": [
      {
        "id": 1,
        "name": "Class A",
        "endMonthDay": "06-30",
        "fullStartDate": "2024-09-01",
        "fullEndDate": "2025-06-30",
        "nextClass": 2,
        "deleteUserAfterClassEnd": false,
        "autoNextClass": true,
        "googleClassroomLink": "https://classroom.google.com/c/...",
        "ssoGroupId": "group_id",
        "lastSsoSync": "2024-09-01T12:00:00Z",
        "updatedAt": "2024-09-07T08:30:00Z",
        "createdAt": "2024-08-30T08:30:00Z",
        "sortPosition": 1
      }
    ],
    "settings": {
      "defaultClass": 1,
      "maxClasses": 5,
      "userCanAddClasses": true
    }
  }
}

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
objects object The main object containing the response data.
objects.classes array An array of classes.
objects.classes[].id integer The unique ID of the class.
objects.classes[].name string The name of the class.
objects.classes[].endMonthDay string The end month and day of the class (MM-DD format).
objects.classes[].fullStartDate string The full start date of the class (YYYY-MM-DD format).
objects.classes[].fullEndDate string The full end date of the class (YYYY-MM-DD format).
objects.classes[].nextClass integer The ID of the next class, if any.
objects.classes[].deleteUserAfterClassEnd boolean Whether to delete the user after the class ends.
objects.classes[].autoNextClass boolean Whether to automatically enroll in the next class.
objects.classes[].googleClassroomLink string The Google Classroom link associated with the class.
objects.classes[].ssoGroupId string The SSO group ID associated with the class.
objects.classes[].lastSsoSync string The timestamp of the last SSO sync, or null if never synced.
objects.classes[].updatedAt string The timestamp of the last update (UTC).
objects.classes[].createdAt string The timestamp of when the class was created (UTC).
objects.classes[].sortPosition integer The sort position of the class.
objects.settings object The settings related to school classes.
objects.settings.defaultClass integer The ID of the default class.
objects.settings.maxClasses integer The maximum number of classes per user, or null if unlimited.
objects.settings.userCanAddClasses boolean Whether the user has permission to add new classes.

Create or update a class

Required permissions
org_school_settings_manage

POST /{id}/account/settings/school/classes/SaveClass

Example Request

{
  "id": 1,
  "name": "Physics 101",
  "endMonthDay": "12-31",
  "fullStartDate": "2024-01-01",
  "fullEndDate": "2024-12-31",
  "autoNextClass": true,
  "nextClass": 2,
  "deleteUserAfterClassEnd": false,
  "googleClassroomLink": "https://classroom.google.com/c/abc123",
  "ssoGroupId": "group1"
}

Request Parameters

Parameter Type Required Description
id integer No The unique ID of the class. If provided, the endpoint updates the existing class; otherwise, a new class is created.
name string Yes The name of the class (maximum length: 16 characters).
endMonthDay string No The end month and day of the class in MM-DD format.
fullStartDate string No The full start date of the class in YYYY-MM-DD format.
fullEndDate string No The full end date of the class in YYYY-MM-DD format.
autoNextClass boolean No Indicates if users should be automatically enrolled in the next class.
nextClass integer No The ID of the next class, if autoNextClass is true.
deleteUserAfterClassEnd boolean No Indicates if the user should be deleted after the class ends.
googleClassroomLink string No The URL to the Google Classroom link associated with the class. Must be a valid HTTPS URL.
ssoGroupId string No The SSO group ID associated with the class.

Response

Parameter Type Description
objects object The main object containing the response data.
objects.class object The saved class object.
objects.class.id integer The unique ID of the class.
objects.class.name string The name of the class.
objects.class.endMonthDay string The end month and day of the class (MM-DD format).
objects.class.fullStartDate string The full start date of the class (YYYY-MM-DD format).
objects.class.fullEndDate string The full end date of the class (YYYY-MM-DD format).
objects.class.autoNextClass boolean Indicates if users are automatically enrolled in the next class.
objects.class.nextClass integer The ID of the next class, if applicable.
objects.class.deleteUserAfterClassEnd boolean Indicates if users should be deleted after the class ends.
objects.class.googleClassroomLink string The Google Classroom link associated with the class.
objects.class.ssoGroupId string The SSO group ID associated with the class.
objects.class.lastSsoSync string The date and time of the last SSO synchronization in UTC format, or null if none.
objects.class.updatedAt string The date and time when the class was last updated in UTC format, or null if none.
objects.class.createdAt string The date and time when the class was created in UTC format, or null if none.
objects.class.sortPosition integer The sort position of the class.

Slicer

List Slicer Profiles

curl 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 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

Custom Fields

Custom Fields allow you to add your own data-fields inside SimplyPrint.

Read more about Custom Fields on our Helpdesk

List custom fields

Required permissions
custom_fields_manage

POST /{id}/custom_fields/Get

Example request

curl -X POST https://api.simplyprint.io/{id}/custom_fields/Get \
    -H 'accept: application/json' \
    -H "X-API-KEY: {API_KEY}" \
    -F "page=1" -F "page_size=10"

Example response

{
  "status": true,
  "message": null,
  "data": [
    {
      "id": 7,
      "fieldId": "student_id",
      "fieldLabel": "Student ID",
      "fieldDescription": "",
      "fieldPlaceholder": null,
      "fieldType": "text",
      "fieldOptions": null,
      "category": "print",
      "subCategory": [
        "user_file",
        "print_queue",
        "print_job"
      ],
      "required": false,
      "enabled": true,
      "defaultValue": null,
      "visibleRequiredPermissions": null,
      "editRequiredPermissions": null,
      "visibleToGroups": [],
      "editableByGroups": [],
      "validation": null,
      "createdByUser": -1,
      "user": "John Doe",
      "forPrinters": [],
      "forModels": [],
      "forGroups": [],
      "showOnRegistration": null,
      "showBeforeStartPrint": null,
      "position": 0,
      "created": "2024-09-07T13:46:59+00:00",
      "updated": "2024-09-07T13:46:59+00:00"
    }
  ],
  "page_amount": 1,
  "total": 1
}

Request

Parameter Type Required Description
page integer yes Which page to show
page_size integer yes Amount of items per page (1-100)
search string no The search filter to apply
sort_id string no What key to sort on (id, fieldId, fieldLabel, fieldDescription, fieldType, category, enabled, created, updated)
sort_dir string no Sort direction (asc, desc)

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
data array List of custom fields.

Create or update a custom field

Required permissions
custom_fields_manage

POST /{id}/custom_fields/Save

Example request

curl -X POST https://api.simplyprint.io/{id}/custom_fields/Save \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{"category":"print","subCategory":["user_file","print_queue","print_job"],"fieldType":"text","fieldId":"student_id","fieldLabel":"Student ID","required":false,"enabled":true}'

Example response

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

Request

Parameter Type Required Description
id integer no If you want to update an existing custom field, specify this
category string yes One of print, user, printer, filament
subCategory array no Array of subcategories. Valid subcategories: print_queue, print_job, user_file
fieldId string yes ID of the field
fieldType string yes One of boolean, text, longtext, number, date, datetime, phone, email, url, select, multiselect, radio, checkbox
fieldLabel string yes Label of the field
fieldOptions object no Field options. An object with one entry, options, whose value is an array of {label: string, value: string}
FieldDescription string no Description of the field
fieldPlaceholder string no Placeholder text for the field
required boolean yes Whether the field is required
defaultValue object no Default value of the field. Object key should be either string, number, boolean, date, options, with the appropriate value type
validation object no Validation rules for the field. Object keys can be any of stringRegex, stringMinLength, stringMaxLength, numberAllowDecimals, numberMinValue, numberMaxValue, validationMessage
forPrinters array no Array of printer IDs the field should be visible for
forModels array no Array of model IDs the field should be visible for
forGroups array no Array of group IDs the field should be visible for
showOnRegistration boolean no Whether the field should be shown on registration
showBeforeStartPrint boolean no Whether the field should be shown before starting a print

Response

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

Enable or disable a custom field

Required permissions
custom_fields_manage

POST /{id}/custom_fields/SetEnabled

Example request

curl -X POST https://api.simplyprint.io/{id}/custom_fields/SetEnabled \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{"id": 123, "enabled": true}'

Example response

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

Request

Parameter Type Required Description
id integer yes ID of the custom field to enable or disable
enabled boolean yes Whether the custom field should be enabled (true) or disabled (false)

Response

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

Delete custom fields

Required permissions
custom_fields_manage

GET /{id}/custom_fields/Delete

Example request

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

Example request with multiple IDs

curl https://api.simplyprint.io/{id}custom_fields/Delete?ids=123,124,125 \
-H 'accept: application/json' \
-H 'X-API-KEY: {API_KEY}'

Example response

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

Request

Parameter Type Required Description
id integer yes (if ids is not provided) The ID of the custom field to delete.
ids string yes (if id is not provided) A comma-separated list of custom field IDs to delete. Valid if multiple fields need to be removed.

Response

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

Custom field submission

POST /{id}/custom_fields/SubmitValues

Example request

curl -X POST https://api.simplyprint.io/{id}/custom_fields/SubmitValues \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{"category": "printer", "subCategory": "print_job", entityIds: [1234], "values": [{customFieldId: "student_id", value: {"string": "1234567890"}}]}'

Example response

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

Request

Parameter Type Required Description
category string yes One of print, user, printer, filament
subCategory string yes One of print_queue, print_job, user_file
entityIds array yes Array of entity IDs to submit values for
values array yes Array of custom field values to submit. Each value looks like {customFieldId: string, value: CustomFieldValue}

Custom field submission value

The value of a custom field when submitted via the API is an object with a key corresponding to the field type. See the examples to the right for the different field types.

A text field would have a value like this:

{
  "string": "1234567890"
}

A number field would have a value like this:

{
  "number": 1234567890
}

A date field would have a value like this:

{
  "date": "2024-09-07"
}

A select field would have a value like this:

{
  "string": "Selected option"
}

A multi-select field would have a value like this:

{
  "options": [
    "Option 1",
    "Option 2"
  ]
}

Webhooks

Webhooks allow you to build or set up integrations that subscribe to certain events on SimplyPrint. When one of those events is triggered, we'll send an HTTP POST payload to the webhook's configured URL.

List webhooks

Required permissions
webhooks_manage

GET /{id}/webhooks/Get

Example request

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

Example response

{
  "status": true,
  "message": null,
  "data": [
    {
      "id": 11,
      "created_by": {
        "id": 12640,
        "first_name": "John",
        "last_name": "Doe",
        "avatar": "https://example.com/avatar.jpg"
      },
      "name": "Example Webhook",
      "url": "https:\/\/actions.nasa.gov\/print_events",
      "events": [
        "job.started",
        "job.paused",
        "job.resumed",
        "job.cancelled",
        "job.done",
        "job.failed",
        "job.bed_cleared"
      ],
      "secret": null,
      "enabled": true,
      "oauth_client_id": null,
      "created_at": "2024-09-07T18:16:51+00:00",
      "updated_at": "2024-09-07T18:16:51+00:00"
    }
  ]
}

Response

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

Create or update a webhook

Required permissions
webhooks_manage

POST /{id}/webhooks/Create

Example request

curl -X POST \
https://api.simplyprint.io/{id}/webhooks/Create \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {API_KEY}' \
-d '{ "name": "Order Created", "description": "Triggers when an order is created", "url": "https://example.com/webhook", "secret": "mysecret", "enabled": true, "events": ["order.created", "order.updated"] }'

Example response

{
  "status": true,
  "message": null,
  "webhook": {
    "id": 123,
    "name": "Order Created",
    "description": "Triggers when an order is created",
    "url": "https://example.com/webhook",
    "secret": "mysecret",
    "enabled": true,
    "events": [
      "order.created",
      "order.updated"
    ],
    "created_by": "User Name",
    "company": "Company Name"
  }
}

Request

Parameter Type Required Description
id integer no The ID of the webhook. Required if updating an existing webhook.
name string yes The name of the webhook.
description string no A description of the webhook.
url string yes The URL where the webhook will send requests. Must be a valid URL.
secret string no A secret key used to sign the webhook payloads.
enabled boolean no Whether the webhook is enabled or not. Default is false.
events array yes A list of events that the webhook will listen to. Must be at least one. Each event should match a valid WebhookEvent.

Response

Parameter Type Description
status boolean True if the request was successful.
message string Error message if status is false.
webhook object Details of the created or updated webhook. Contains fields like id, name, url, events, etc.

Delete a webhook

Required permissions
webhooks_manage

POST /{id}/webhooks/Delete

Example request

curl -X POST \
https://api.simplyprint.io/{id}/webhooks/Delete \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {API_KEY}' \
-d '{"id": 123}'

Example response

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

Request

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

Response

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

Enable or disable a webhook

Required permissions
webhooks_manage

POST /{id}/webhooks/SetEnabled

Example request

curl -X POST \
https://api.simplyprint.io/{id}/webhooks/SetEnabled \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {API_KEY}' \
-d '{"id": 123, "enabled": true}'

Example response

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

Request

Parameter Type Required Description
id integer yes The ID of the webhook to enable or disable.
enabled boolean yes Set to true to enable or false to disable.

Response

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

Manually trigger webhook

The event type will be test.

POST /{id}/webhooks/TriggerTestWebhook

Example request

curl -X POST \
https://api.simplyprint.io/{id}/webhooks/TriggerTestWebhook \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-KEY: {API_KEY}' \
-d '{"id": 123}'

Example response

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

Request

Parameter Type Required Description
id integer yes The ID of the webhook to trigger.

Response

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

WebhookEvent

Event Name Description
job.started Triggered when a job is started.
job.paused Triggered when a job is paused.
job.resumed Triggered when a job is resumed.
job.cancelled Triggered when a job is cancelled.
job.done Triggered when a job is done.
job.failed Triggered when a job has failed.
job.bed_cleared Triggered when the bed is cleared.
printer.autoprint_state_changed Triggered when the autoprint state of a printer is changed.
printer.nozzle_size_changed Triggered when the nozzle size of a printer is changed.
printer.material_changed Triggered when the material of a printer is changed.
printer.custom_tag_assigned Triggered when a custom tag is assigned to a printer.
printer.custom_tag_detached Triggered when a custom tag is detached from a printer.
company.autoprint_state_changed Triggered when the autoprint state of a company is changed.

GCode Macros

Get overview

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

Success response

{
  "status": true,
  "message": null,
  "gcodeCompletions": [
    {
      "label": "G0",
      "type": "variable",
      "info": "Add a straight line movement to the planner",
      "detail": "X, Y, Z, E, F, S"
    }
  ],
  "macro_groups": [
    {
      "name": "<i class='fas fa-infinity'><\/i> AutoPrint <i>(advanced)<\/i>",
      "desc": "The AutoPrint feature can automatically start prints. Here you define what Gcode should be executed to make sure the bed is clear.",
      "macros": [
        "is_autoprint_clear"
      ],
      "nopersonal": true
    }
  ],
  "macros_cards": {
    "is_start": {
      "name": "Start print",
      "description": "GCODE to be executed at start of print when using our slicer"
    }
  },
  "macros": {
    "company": [
      {
        "gcodes": {
          "printer_225": [
            "{snippet:2731}"
          ],
          "printer_10063": null,
          "printer_10372": [
            "{snippet:2796}"
          ]
        },
        "type": "is_start"
      }
    ],
    "personal": null,
    "sp": [
      {
        "gcodes": {
          "type_0": [
            "{snippet:26}"
          ],
          "type_236": [
            "{snippet:1103}",
            "{snippet:26}"
          ]
        },
        "type": "is_pause"
      }
    ]
  },
  "snippets": {
    "company": [
      {
        "id": 28,
        "name": "Indentify Ender 5",
        "description": "Identify printer specifically for Ender 5",
        "priority": 0,
        "created": "2020-04-22T09:19:37+00:00"
      }
    ]
  },
  "variables": {
    "bed_x": "Printer bed X length in mm",
    "bed_y": "Printer bed Y length in mm"
  },
  "slicerVariables": {
    "temp": "Hot end temperature",
    "bed_temp": "Bed temperature",
    "fan_speed": "Active cooling fan speed (usually 0-255)"
  }
}

GET /{id}/gcode_macros/GetOverview

Response

See example response.

Get snippet

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

Success Response

{
  "status": true,
  "message": null,
  "snippet": {
    "id": 123,
    "name": "Example Snippet",
    "description": "This is an example snippet",
    "priority": 0,
    "gcode": "G1 X10 Y10"
  }
}

GET /gcode_macros/GetSnippet

Request Parameters

Parameter Type Description
id integer The ID of the snippet to retrieve.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
snippet object The details of the snippet.
snippet.id integer Unique identifier for the snippet.
snippet.name string Name of the snippet.
snippet.description string Description of the snippet.
snippet.priority integer Priority of the snippet.
snippet.gcode string? GCode content of the snippet (if any).

Save snippet

curl -X POST https://api.simplyprint.io/{id}/gcode_macros/SaveSnippet?id=123&type=private \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "name": "Updated Snippet",
    "description": "This is an updated snippet.",
    "gcode": ["G1 X10 Y10", "G1 X20 Y20"]
  }'

Success Response

{
  "status": true,
  "message": null,
  "new_data": {
    // Updated data of the GCODE snippets
  }
}

POST /gcode_macros/SaveSnippet

Request Parameters

Parameter Type Description
id integer The ID of the snippet to update (optional for creating a new snippet).
type string The type of the snippet (org, private, public).

Request Body

Parameter Type Description
name string The name of the GCODE snippet.
description string The description of the snippet.
gcode array The GCODE commands of the snippet.
gcode.* string A single GCODE command.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
created integer The ID of the newly created snippet (if applicable).
new_data object The updated data of the GCODE snippets.

Delete snippet

curl -X POST https://api.simplyprint.io/{id}/gcode_macros/DeleteSnippet?id=123 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success Response

{
  "status": true,
  "message": null,
  "new_data": {
    // Updated data of the GCODE snippets
  }
}

POST /gcode_macros/DeleteSnippet

Request Parameters

Parameter Type Description
id integer The ID of the snippet to delete (required if ids is not provided).
ids string Comma-separated list of IDs of snippets to delete (required if id is not provided).

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
new_data object The updated data of the GCODE snippets.

Get macro

curl https://api.simplyprint.io/{id}/gcode_macros/GetMacroGcode?macro=is_start&printer=123&model=456&org=true&private=false&public=true \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \

Success Response

{
  "status": true,
  "message": null,
  "gcode": [
    "G1 X10 Y10",
    "G1 X20 Y20"
  ],
  "multiple": false
}

GET /gcode_macros/GetMacroGcode

Request Parameters

Parameter Type Description
macro string The type of the macro. Must be one of the enums defined in GcodeMacroType.
printer integer The ID of the printer.
model integer The ID of the printer model.
org boolean Whether to include organization macros.
private boolean Whether to include private macros.
public boolean Whether to include public macros.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
gcode array The GCODE commands of the macro.
multiple boolean Whether multiple GCODEs are returned.

Save macro

curl -X POST https://api.simplyprint.io/gcode_macros/SaveMacro?type=private \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
  "type": "is_start",
  "gcodes": {"printer_225": ["G1 X10 Y10"], "type_123": ["G1 X20 Y20", "{snippet:123}"]}
  }'

Success Response

{
  "status": true,
  "message": null
}
Required permission Description
gcode_profiles Required if macro is of type org.

POST /gcode_macros/SaveMacro

Request Parameters

Parameter Type Description
type string One of org, private

Request Body

Parameter Type Description
type string One of is_start, is_end, is_cancel, is_pause, is_resume, is_autorpint_clear
gcodes object Content of the macro.
gcodes.printer_{id} array GCODE commands for the printer with ID {id}.
gcodes.type_{id} array GCODE commands for the printer model with ID {id}.
gcodes.*[] string Can be a GCODE command or {snippet:{id}} to reference a snippet.

Response

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

Arrange gcode order in macro

curl -X POST https://api.simplyprint.io/gcode_macros/Arrange \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "order": [4,2,3,1]
  }'

Success Response

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

POST /gcode_macros/Arrange

Request Parameters

Parameter Type Description
order array An array of snippet IDs in the desired order.
order.* integer A single snippet ID.

Response

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

Courses

Get course

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

Success response

{
  "status": true,
  "message": null,
  "course": {
    // Course details
  },
  "slides": [
    // Course slides
  ],
  "embeds": [
    {
      "name": "Embed",
      "logo": "example.png",
      "privacy_policy": "https://example.com/privacy",
      "allowed_url": "https://example.com/embed",
      "how_to_embed_guide": "https://example.com/embed_guide"
    }
  ]
}
Required permission Description
courses_view Required to view courses.
courses_manage Required for teacher view.

GET /{id}/courses/GetCourse

Request Parameters

Parameter Type Description
id integer The ID of the course to retrieve.
teacher_view boolean Whether to retrieve the course in teacher view mode.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
course object The course details.
slides array The slides of the course.
embeds array The embed types for the course.

Delete course

curl -X POST https://api.simplyprint.io/{id}/courses/DeleteCourse \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "id": 123
  }'

Success response

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

POST /{id}/courses/DeleteCourse

Request Body

Parameter Type Description
id integer The ID of the course to delete.

Response

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

Move course

curl -X POST https://api.simplyprint.io/{id}/courses/MoveCourse \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "course": 123,
    "category": 456
  }'

Success response

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

POST /{id}courses/MoveCourse

Request Body

Parameter Type Description
course integer The ID of the course to move.
category integer The ID of the new category.

Response

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

Publish/unpublish course

curl -X POST https://api.simplyprint.io/{id}/courses/PublishCourse \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "id": 123
  }'

Success response

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

POST /{id}/courses/PublishCourse

Request Parameters

Parameter Description
unpublish Set if the course should be unpublished (no value required).

Request Body

Parameter Type Description
id integer The ID of the course to publish.

Response

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

Create/update category

curl -X POST https://api.simplyprint.io/{id}/courses/CreateCategory \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "name": "New Category",
    "public": true
  }'

Success response

{
  "status": true,
  "message": null,
  "category": {
    "id": 123,
    "name": "New Category",
    "public": true
  }
}
Required permissions
courses_manage

POST /{id}/courses/CreateCategory

Request Body

Parameter Type Description
language string The language code (2 characters) (optional).
id integer The ID of the category to update (optional to update existing category).
name string The name of the category.
public boolean Whether the category is public.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
category object The created or updated category details.

Delete category

curl -X POST https://api.simplyprint.io/{id}/courses/DeleteCategory \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "id": 123
  }'

Success response

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

POST /{id}/courses/DeleteCategory

Request Body

Parameter Type Description
id integer The ID of the category to delete.

Response

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

Partner

Get companies

curl -X POST https://api.simplyprint.io/{id}/partner/GetCompanies \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "page": 1,
    "page_size": 10,
    "search": "example",
    "sort_id": "name",
    "sort_dir": "asc"
  }'

Success response

{
  "status": true,
  "message": null,
  "data": [
    // List of companies
  ],
  "total": 100,
  "page_amount": 10
}

POST /{id}/partner/GetCompanies

Request Body

Parameter Type Description
page integer The page number to retrieve.
page_size integer The number of items per page (between 1 and 100).
search string Search term to filter companies (max 50 chars).
sort_id string The field to sort by.
sort_dir string The direction to sort (asc or desc).

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
data array The list of companies.
total integer The total number of companies.
page_amount integer The total number of pages.

Get company

curl https://api.simplyprint.io/{id}/partner/GetCompany?company=123&initial=true \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

{
  "status": true,
  "message": null,
  "data": {
    "id": 123,
    "name": "Example Company",
    "vat": "12345678",
    "ean": "1234567890123",
    "trial_until": "2023-12-31T23:59:59",
    "country": "US",
    "uid": "unique-id",
    "created": "2023-01-01T00:00:00",
    "active": true,
    "sponsored": false,
    "public_edu": true,
    "plan": "premium",
    "type": "business",
    "max_printers": 10,
    "max_users": 50,
    "user_max_gb": 100,
    "address": "123 Example St",
    "contact_person": "John Doe",
    "contact_email": "john.doe@example.com",
    "contact_phone": "+1234567890",
    "user_count": 25,
    "printers_count": 5,
    "online_printers": 3,
    "week_jobs": 10,
    "total_jobs": 100,
    "filament": 20,
    "success_jobs": 8,
    "online_user_count": 15,
    "user_space_used": 50
  },
  "users_data": {
    // Initial user data if applicable
  }
}

GET /{id}/partner/GetCompany

Request Parameters

Parameter Type Description
company integer The ID of the company to retrieve.
initial boolean Whether to include initial user data (optional).

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
data object The company details.
users_data object Initial user data if initial is true.

Get overview stats

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

Success response

{
  "status": true,
  "message": null,
  "total_active_managed_companies": 10,
  "total_trial_managed_companies": 2,
  "total_inactive_managed_companies": 3,
  "total_printers": 50,
  "total_online_printers": 30,
  "total_print_jobs": 200,
  "total_print_jobs_last_7_days": 20,
  "total_users": 100,
  "total_users_online_last_7_days": 15
}

GET /{id}/partner/GetOverviewStats

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
total_active_managed_companies integer Total number of active managed companies.
total_trial_managed_companies integer Total number of managed companies in trial.
total_inactive_managed_companies integer Total number of inactive managed companies.
total_printers integer Total number of printers for all managed companies.
total_online_printers integer Total number of online printers for all managed companies.
total_print_jobs integer Total number of print jobs for all managed companies.
total_print_jobs_last_7_days integer Total number of print jobs in the last 7 days.
total_users integer Total number of users for all managed companies.
total_users_online_last_7_days integer Total number of users online in the last 7 days.

Create/update company

curl -X POST https://api.simplyprint.io/{id}/partner/CreateCompany \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "name": "Example Company",
    "uid": "unique-id",
    "active": 1,
    "trial_until": "2023-12-31",
    "public_edu": true,
    "extra_printers": 5,
    "extra_users": 50,
    "extra_gb": 100,
    "active_plan": 5,
    "type": 1,
    "contact_email": "contact@example.com",
    "contact_phone": "+1234567890",
    "att_person": "John Doe",
    "uni_login": true,
    "uni_login_ids": "id1,id2",
    "address_stuff": {
      "street": "123 Example St",
      "city": "Example City",
      "country": "US",
      "postal_code": "12345"
    }
  }'

Success response

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

POST /{id}/partner/CreateCompany

Request Parameters

Parameter Type Description
edit integer The ID of the company to edit (optional).

Request Body

Parameter Type Description
name string The name of the company (required, max 128 characters).
uid string The unique identifier for the company (required, max 32 characters).
active integer Whether the company is active (required, 0 or 1).
trial_until date The trial end date in Y-m-d format (optional).
public_edu boolean Whether the company is a public educational institution (required).
extra_printers integer The number of extra printers (required, min 0).
extra_users integer The number of extra users (required, min 0).
extra_gb integer The amount of extra storage in GB (required, min 0).
active_plan integer The active plan ID (required, must be 4 or 5).
type integer The type of company (required, must be 0, 1, 2, or 3).
contact_email string The contact email for the company (required, valid email format).
contact_phone string The contact phone number (optional, max 32 characters).
att_person string The name of the contact person (required, max 128 characters).
uni_login boolean Whether UniLogin is enabled (optional).
uni_login_ids string Comma-separated UniLogin IDs (optional).
address_stuff array The address details (required).

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
id integer The ID of the created or updated company.

Delete company

curl -X POST https://api.simplyprint.io/{id}/partner/DeleteCompany?company=123 \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}'

Success response

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

POST /{id}/partner/DeleteCompany

Request Parameters

Parameter Type Description
company integer The ID of the company to delete.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false. 
curl -X POST https://api.simplyprint.io/{id}/partner/move/ValidatePrinter \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "ids": [1, 2, 3],
    "search": "example",
    "not_in": [4, 5]
  }'

Success response

{
  "status": true,
  "message": null,
  "items": [
    {
      "id": 1,
      "name": "Printer 1",
      "sku": "SKU123",
      "org_id": 10,
      "image": "https://example.com/printer1.jpg"
    },
    {
      "id": 2,
      "name": "Printer 2",
      "sku": "SKU456",
      "org_id": 11,
      "image": "https://example.com/printer2.jpg"
    }
  ]
}

Searches for printers across all partner-companies. Useful for finding printers to move between companies.

POST /{id}/partner/move/ValidatePrinter

Request Body

Parameter Type Description
ids array List of printer IDs to search (optional).
ids.* integer Each printer ID must be an integer.
search string Search term to filter printers (optional, max 256 chars).
not_in array List of printer IDs to exclude (optional).
not_in.* integer Each printer ID to exclude must be an integer.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
items array List of validated printers.
items.*.id integer The ID of the printer.
items.*.name string The name of the printer.
items.*.sku string The SKU of the printer.
items.*.org_id integer The ID of the company owning the printer.
items.*.image string URL of the printer's image.

Move printer

curl -X POST https://api.simplyprint.io/{id}/partner/move/MovePrinter \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "moveTo": 123,
    "moveToGroup": 456,
    "ids": [1, 2, 3]
  }'

Success response

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

Find printers to move with ValidatePrinter endpoint.

POST /{id}/partner/move/MovePrinter

Request Parameters

Parameter Type Description
moveTo integer The ID of the target company (required).
moveToGroup integer The ID of the target printer group (required).
ids array List of printer IDs to move (required).
ids.* integer Each printer ID must be an integer.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false. 
curl -X POST https://api.simplyprint.io/{id}/partner/move/ValidateFilament \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "ids": [1, 2, 3],
    "search": "example filament",
    "not_in": [4, 5]
  }'

Success response

{
  "status": true,
  "message": null,
  "items": [
    {
      "id": 1,
      "uniq_id": "UNIQ123",
      "color_name": "Red",
      "color_hex": "#FF0000",
      "org_id": 10,
      "brand": "Example Brand",
      "type_id": 1,
      "type_name": "PLA"
    }
  ]
}

Searches for filaments across all partner-companies. Useful for finding filaments to move between companies.

POST /{id}/partner/move/ValidateFilament

Request Body

Parameter Type Description
ids array List of filament IDs to search (optional).
ids.* integer Each filament ID must be an integer.
search string Search term to filter filament (optional, max 256 chars).
not_in array List of filament IDs to exclude (optional).
not_in.* integer Each filament ID to exclude must be an integer.

Response

Parameter Type Description
status boolean true if the request was successful.
message string Error message if status is false.
items array List of validated filaments.
items.*.id integer The ID of the filament.
items.*.uniq_id string The unique ID of the filament.
items.*.color_name string The name of the filament color.
items.*.color_hex string The hex code of the filament color.
items.*.org_id integer The ID of the company owning the filament.
items.*.brand string The brand of the filament.
items.*.type_id integer The ID of the filament type.
items.*.type_name string The name of the filament type.

Move filament

curl -X POST https://api.simplyprint.io/{id}/partner/move/MoveFilament \
  -H 'accept: application/json' \
  -H 'X-API-KEY: {API_KEY}' \
  -d '{
    "moveTo": 123,
    "moveToFilamentType": 456,
    "filamentMoveTypeClean": false,
    "ids": [1, 2, 3]
  }'

Success response

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

Find filament to move with ValidateFilament endpoint.

POST /{id}/partner/move/MoveFilament

Request Parameters

Parameter Type Description
moveTo integer The ID of the target company (required).
moveToFilamentType integer The ID of the target filament type (required).
filamentMoveTypeClean boolean Whether to only change the filament company, or also change the type (optional).
ids array List of printer IDs to move (required).
ids.* integer Each printer ID must be an integer.

Response

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

Permissions and Scopes

Company permissions

These permissions are used to control access within a company. The permissions are tied to the user groups within the company.

The owner of a company has all permissions.

Permission Description
view_news "Allow viewing news in the application"
org_admin "Allow administrating organization settings and permissions"
panel_printing "Allow access to the printing panel"
printer_restart "Allow restarting printers"
printer_edit "Allow creating, editing, and deleting printers"
bed_leveling "Allow performing bed leveling on printers"
gcode_profiles "Allow managing GCode macros and snippets"
printer_settings "Allow configuring printer settings"
filament_settings "Allow managing filament settings"
change_filament "Allow changing filament on printers"
create_filament "Allow creating, editing, and deleting filament spools"
see_filament_tab "Allow viewing the filament tab"
view_users "Allow viewing user overview in the organization"
change_user_rank "Allow changing users' group (rank) within the organization"
assign_peer_rank "Allow assigning other users' group (rank) to the same rank as yours"
manual_user_email_confirm "Allow manually confirming user email addresses"
invite_users "Allow inviting other users to the organization"
delete_user "Allow deleting users from the organization"
org_user_registration_settings "Allow managing user registration settings for the organization"
org_hub_settings "Allow managing hub settings for the organization"
org_rank_management "Allow creating, editing, deleting, and reordering user groups (ranks)"
org_view_statistics "Allow viewing organization-wide statistics (for all users)"
refill_quota "Allow refilling user quota (coming soon)"
custom_slicer_profiles "Allow creating and deleting custom slicer profiles"
org_profiles "Allow creating and editing organization slicer profiles"
all_slicer_modes "Allow accessing all slicer modes"
see_slicer_default_profiles "Allow viewing default slicer profiles"
queue_remove_all "Allow deleting other users' print queue items"
org_api "Allow users' API key to be used with this organization"
create_org_folder "Allow creating organization (shared) folders"
cancel_others "Allow canceling other users' print jobs"
see_who_printed "Allow viewing who printed specific items in various popups ("Print removed", "Cancel print", etc.)"
edit_tags "Allow creating, updating, and deleting custom tags"
goto_local "Allow going to local printer UI (OctoPrint, Mainsail, Fluidd, etc.)"
printer_info "Allow viewing extra printer information ("Printer info" popup)"
send_raw_gcode "Allow sending raw GCode commands to printers"
widget_device_health "Allow access to device health widget"
widget_control "Allow access to printer control widget"
change_temps "Allow changing printer temperatures"
change_print_speed "Allow changing the print speed"
printer_delete "Allow deleting printers"
printer_add "Allow adding new printers"
print_queue "Allow access to the print queue"
reorder_queue "Allow reordering print queue items"
see_cam "Allow viewing printer camera feeds"
clear_bed "Allow clearing the print bed"
slice "Allow slicing models for printing"
print "Allow starting print jobs"
pause "Allow pausing print jobs"
cancel "Allow canceling print jobs"
queue_groups "Allow managing print queue groups"
queue_edit_others "Allow editing other users' print queue items"
queue_read_notes "Allow reading notes on other users' print queue items"
queue_download_others "Allow downloading files from other users' print queue items"
queue_see_done_items "Allow viewing completed print queue items"
queue_revive_done_items "Allow reviving completed print queue items"
queue_assign_printers "Allow assigning printers to print queue items"
queue_print_slice "Allow printing directly from sliced items in the queue"
queue_see_others "Allow viewing other users' print queue items"
files_nozzle_tag "Allow managing nozzle tags for files"
files_material_tag "Allow managing material tags for files"
files_assign_custom_tags "Allow assigning custom tags to files"
queue_nozzle_tag "Allow managing nozzle tags for queue items"
queue_material_tag "Allow managing material tags for queue items"
queue_assign_custom_tags "Allow assigning custom tags to queue items"
can_export "Allow exporting data (CSV export)"
autoprint_manage "Allow managing AutoPrint settings"
courses_manage "Allow managing courses"
courses_view "Allow viewing courses"
webhooks_manage "Allow managing webhooks"
set_user_teacher "Allow setting a user as a teacher ("School" plan only)"
change_user_school_class "Allow changing user's school class ("School" plan only)"
org_school_settings_manage "Allow managing school settings for the organization ("School" plan only)"
access_all_printers "Allow access to all printers in the organization"
custom_fields_manage "Allow creating and deleting custom fields"

OAuth2 scopes

These scopes are used to control access to the API. The scopes are tied to the OAuth2 access token.

Scope Description
user.read View user details
printers.read View printer details
printers.write Manage details of printers
printers.actions Perform actions on printers
spools.read View filament spools
spools.write Manage filament spools
files.read View file and folder details and contents
files.write Manage files and folders
files.temp_upload Upload temporary files
queue.read View print queue
queue.write Manage print queue
statistics.read View printing statistics
print_history.read View print history
slicer.read View slicer profiles
slicer.write Manage slicer profiles
tags.read View tags
tags.write Manage 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/null
cURL