Technical details
Requests need to have the following content type for sending parameters:
Content-Type: application/x-www-form-urlencoded
Test environment endpoint: https://acorn.3dprinteros.com/
Live environment endpoint: https://cloud.3dprinteros.com/
Table of contents
User login
User logout
Check session
File Upload
Get the user’s projects list
Get Workgroups list
Get an organized printer list
Get printer jobs list
Get detailed job info
Get slicer settings for the gcode file
Update gcode file metadata (set printer type id for gcode file)
Get printer types used in the cloud (non-industrial)
Get the list of shares for the printer
Share the printer with the user
Unshare printer
Add printer by registration code
Get the list of accessible user printers
Get users in the Workgroup
Add user to Workgroup
Delete the user from Workgroup
Get printer types used in the cloud (non-industrial, with printer parameters field)
Get the custom report for organizational admins/moderators
Get a camera list token (internal usage)
User login/registration using Google OAuth token id
Confirmation of GDPR flags and user registration
Create organization user
Get finished jobs report
File Slice Action [in development]
Print File
Start print job [in development]
Pause printer
Unpause (resume) printer
Cancel print job
Update user settings
Clear Cloud’s emulated “Build Tray is clear” flag
1. User login
1. URL: /apiglobal/login [POST Request]
2. Parameters:
username - text
password - text
3. Response:
SUCCESS (code 200):
{result: true, message: {session: text}}FAIL (code not 200):
{result: false, message: error_text}
2. User logout
1. URL: /apiglobal/loginout [POST Request]
2. Parameters:
session
3. Response:
SUCCESS (code 200):
{result: true, message: []}FAIL (code not 200):
{result: false, message: error_text}
3. Check session
1. URL: /apiglobal/check_session [POST Request]
2. Parameters:
session
3. Response:
SUCCESS (code 200):
{result: true, message: “Session is valid”}FAIL (code not 200):
{result: false, message: error_text}
4. File Upload
1. URL: /apiglobal/upload [POST Request]
2. Parameters:
session
file: file object
project_id: int (if you need to upload into some project, else null or not use)
project_name: text (if you need to create a new project or use existed without project_id, else null or not use)
project_color: text (if you need to create a new project or use existed without project_id, else null or not use)
upload_type_id: int, optional (if you need to set upload type other than Website Upload (7 for Plugin upload), else null or not use)
upload_soft_name: text, optional (if you need to set upload software name, else null or not use)
3. Response:
SUCCESS (code 200):
{result: true, message: {file_id: int, show_select_printers: bool, project_id: int, slicer: text}}FAIL (code not 200):
{result: false, message: error_text}
5. Get the user’s projects list
1. URL: /apiglobal/get_projects [POST Request]
2. Parameters:
session
3. Response:
SUCCESS (code 200):
{result: true, message: [{id: int, name: text, color: text}, ...]}FAIL (code not 200):
{result: false, message: error_text}
6. Get Workgroups list
1. URL: /apiglobal/get_workgroups_simple_list [POST Request]
2. Parameters:
session
3. Response:
SUCCESS (code 200):
{result: true, message: [{id: int, name: text, rights: int (2-can print, 3-can queue)}, ...]}FAIL (code not 200):
{result: false, message: error_text}
7. Get an organized printer list
1. URL: /apiglobal/get_organization_printers_list [POST Request]
2. Parameters:
session
printer_id (int, optional)
workgroup_id (int, optional)
3. Response:
SUCCESS (code 200):
{result: true, message: [{id: int, name: text, type: text, snr: text, host_num: text, local_ip: text, workgroups: [int, ...]|null, state: text, temps: [int, int, ...]|null}, target_temps: [int, int, …]|null}, percent: int}, ...]}FAIL (code not 200):
{result: false, message: error_text}
8. Get printer jobs list
1. URL: /apiglobal/get_printer_jobs [POST Request]
2. Parameters:
session
printer_id (int)
limit (int, optional, default 20): max job count in response
offset (int, optional, default 0): offset for pagination
prev_time (datetime): optional parameter, for live update. Can be used to get only changed jobs between two requests. For the first request, you have to send prev_time: 0, and you will have a “time” parameter in response. You have to send prev_time: “time” in next request to get only live updates
is_actual (0 or 1, optional, default 0) - provide all the Active jobs (In queue or printing) and Ended jobs (Finished, Aborted, Failed; for a 24 hours period of ending (or if organization has a different settings in the Org Settings, it will substitute the period))
3. Response:
SUCCESS (code 200):
{"result":true,"message":[{"id":"int, job id", "status_id":"int, status of job", "filename":"text, gcode file name", "datetime":"text, datetime of job creating", "email":"text, email of user who created the job"}, …]}Status_id values: 11 - in queue, 21 - in progress, 43 - job failed, 45 - job aborted, 77 - job finished.
FAIL (code not 200):
{result: false, message: error_text}
4. Response example:
{"result":true,"message":[
{"id":"26590","status_id":"11","filename":"micro_sim_adapter.gcode","datetime":"2016-08-18 20:39:52","email":"user@org_mail_domain.com"},
{"id":"26582","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-08-03 01:33:34","email":"user@org_mail_domain.com"},
{"id":"26581","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-08-03 01:31:29","email":"user@org_mail_domain.com"},
{"id":"26580","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-08-03 01:27:10","email":"user@org_mail_domain.com"},
{"id":"26579","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-08-03 01:26:23","email":"user@org_mail_domain.com"},
{"id":"26576","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-08-03 01:23:17","email":"user@org_mail_domain.com"},
{"id":"26549","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-07-28 14:34:42","email":"user@org_mail_domain.com"},
{"id":"26543","status_id":"11","filename":"micro_sim_adapter_V.gcode","datetime":"2016-07-28 13:58:46","email":"user@org_mail_domain.com"},
{"id":"26503","status_id":"45","filename":"micro_sim_adapter.gcode","datetime":"2016-04-01 23:34:42","email":"user@org_mail_domain.com"}]}
9. Get detailed job info
1. URL: /apiglobal/get_job_info [POST Request]
2. Parameters:
session
job_id (int)
3. Response:
SUCCESS (code 200):
{"result":true,"message":{ "id":"int, job id", "status_id":"same as in 9", "datetime":"same as in 9", "printer_id":"int, id of printer", "print_time":"int, real print time, seconds", "gif_image":”text, file name for gif image, or null if no gif image exists”, "picture":"text, file name for preview image", "notes":”text, note for job added on time creating”, "file_id":"int, id of file in job", "filename":"same as in 9", "file_size":"int, size of file, bytes", "printing_duration":"int, estimated print time, seconds", "material_type":"text, estimated material, ABS or PLA", "layer_height":"float, calculated layer_height", "extruders":"json, target extruder temps; weight and material for multi extruder prints", "weight":"float, estimated weight, gramms", "heated_bed":"text, has heated bed, t or f", "heated_bed_temperature":"int, temp of bed", "raft":"text, use raft, t or f ", "supports":"text, use supports, t or f ", "file_cost":”float, estimated cost of the file or null if not used”, "cost":”float, cost of job or null if not used”, "email":"same as in 9" }}Url for gif image: Acorn: https://acornstorage.blob.core.windows.net/gif/ + job[‘gif_image’] | Cloud: https://live3dprinteros.blob.core.windows.net/gif/ + job[‘gif_image’]
Url for preview image: Acorn: https://acornstorage.blob.core.windows.net/render/ + job[‘picture’] | Cloud: https://live3dprinteros.blob.core.windows.net/render/ + job[‘picture’]
FAIL (code not 200):
{result: false, message: error_text}
4. Response example:
{"result":true,"message":{
"id":"26582",
"status_id":"11",
"datetime":"2016-08-03 01:33:34",
"printer_id":"24052",
"print_time":"0",
"gif_image":null,
"picture":"9cd9f04146cb6ce84c926a40a7b4d01b68b1723e74f97c0fda07ccdbfba6132f.png",
"notes":null,
"file_id":"58652",
"filename":"micro_sim_adapter_V.gcode",
"file_size":"32842",
"printing_duration":"100",
"material_type":"ABS",
"layer_height":"0",
"color_numbers":"1",
"extruders":"{\"R\":230,\"L\":0}",
"weight":"0.11",
"heated_bed":"t",
"heated_bed_temperature":"110",
"raft":"f",
"supports":"f",
"file_cost":null,
"cost":null,
"email":"user@org_mail_domain.com"
}}
10. Get slicer settings for the gcode file
1. URL: /apiglobal/get_slicer_settings_for_gcode [POST Request]
2. Parameters:
session
file_id (int)
3. Response:
SUCCESS (code 200):
{result: true, message: {associative array, slicer settings}}FAIL (code not 200):
{result: false, message: error_text}
4. Response example:
{"success":true,"result":{
"printer_type_id":"50",
"layer_height":"0.15",
"wall_thickness":"0.8",
"nozzle_size":"0.4",
"bottom_thickness":"0.3",
"filament_diameter":"2.85",
"filament_flow":"100",
"solid_top":"1",
"solid_bottom":"1",
"solid_layer_thickness":"0.7",
"fill_overlap":"15",
"bottom_layer_speed":"20",
"print_speed":"50",
"infill_speed":"50",
"travel_speed":"150",
"fan_enabled":"1",
"fan_speed":"100",
"fan_speed_max":"100",
"support":"None",
"support_type":"Lines",
"support_angle":"60",
"support_fill_rate":"15",
"support_xy_distance":"0.7",
"support_z_distance":"0.15",
"retraction_enable":"1",
"retraction_amount":"4.5",
"retraction_speed":"40",
"retraction_min_travel":"1.5",
"retraction_dual_amount":"16.5",
"retraction_minimal_extrusion":"0.02",
"retraction_combing":"1",
"overlap_dual":"0.15",
"cool_min_layer_time":"5",
"cool_min_feedrate":"10",
"cool_head_lift":"1",
"fan_full_height":"5",
"fill_density":"10",
"platform_adhesion":"None",
"skirt_gap":"3",
"skirt_line_count":"3",
"skirt_minimal_length":"150",
"brim_line_count":"20",
"raft_margin":"5",
"raft_line_spacing":"3",
"raft_base_thickness":"0.6",
"raft_base_linewidth":"1.2",
"raft_interface_thickness":"0.35",
"raft_interface_linewidth":"0.6",
"raft_airgap":"0.2",
"raft_surface_layers":"1",
"object_sink":"0",
"layer0_width_factor":"100",
"print_bed_temperature":"110",
"print_temperature":"230",
"extruderOffset[1":"0",
"posx":"100000",
"posy":"100000",
"extra":"-m 1.00.00.00.01.00.00.00.01.0",
"startCode":"M140 S{print_bed_temperature}\nM190 S{print_bed_temperature}\nM109 T0 S{print_temperature}\nT0\nG21\nG90\nM82\nM107\nG28 X0 Y0\nG28 Z0\nG1 Z15.0 F9000\nG92 E0\nG1 F200 E3\nG92 E0\nG1 F9000\nM117 Printing...",
"endCode":"M104 S0\nM140 S0\nG91\nG1 E-1 F300\nG1 Z+0.5 E-5 X-20 Y-20 F9000\nG28 X0 Y0\nM84\nG90",
"p_chk":"false",
"printer_template_id":"67",
"printer_template_index":"0",
"centered":"true",
"f_material":"ABS",
"file_id":"58627",
"state":3,
"slicer_app_id":3}}
11. Update gcode file metadata (set printer type id for gcode file)
1. URL: /apiglobal/file_update [POST Request]
2. Parameters:
session
updates: {file_id (int): { ptype: int (printer type id), gtype: text (optional, slicer name: Simplify3D, Cura, UltiGCode, Miracle-Grue, FlashForge), zip: boolean (optional, true|false, create zip file for gcode)}, ...}
3. Response:
SUCCESS (code 200):
{result: true, message: []}FAIL (code not 200):
{result: false, message: error_text}
12. Get printer types used in the cloud (non-industrial)
1. URL: /apiglobal/get_printer_types [POST Request]
2. Parameters:
session
3. Response:
SUCCESS (code 200):
{result: true, message: [{id: int, description: text}, ...]}FAIL (code not 200):
{result: false, message: error_text}
13. Get the list of shares for the printer
1. URL: /apiglobal/get_printer_shares [POST Request]
2. Parameters:
session
printer_id (int)
3. Response:
SUCCESS (code 200):
{result: true, message: [{ id: int, share id for unshare action, email: text, number_of_prints: int|null (count of quotes available, if was used on share action), printer_ownership_id: int}, ...]}FAIL (code not 200):
{result: false, message: error_text}
14. Share the printer with the user
1. URL: /apiglobal/share_printer [POST Request]
2. Parameters:
session
printer_id (int)
role_id (int, 2 - can print, 5 - can queue; values could be changed in future)
user_email (text, email of user to share printer)
number_of_prints (optional, int or null or not used; the number of prints available for user with this printer)
3. Response:
SUCCESS (code 200):
{result: true, message: [id: int, share id for unshare action]}FAIL (code not 200):
{result: false, message: error_text}
15. Unshare printer
1. URL: /apiglobal/unshare_printer [POST Request]
2. Parameters:
session
share_id (int, id of share)
3. Response:
SUCCESS (code 200):
{result: true, message: []}FAIL (code not 200):
{result: false, message: error_text}
16. Add printer by registration code
1. URL: /apiglobal/add_printer_by_registration_code [POST Request]
2. Parameters:
session
registration_code (text, registration code)
3. Response:
SUCCESS (code 200):
{result: true, message: {“printer_id”: int}}FAIL (code not 200):
{result: false, message: error_text}
17. Get the list of accessible user printers
1. URL: /apiglobal/get_printers_list [POST Request]
2. Parameters:
session
printer_type (optional, text, printer short type, ex. K_PORTRAIT)
printer_id (optional, int (or array of int for multiple printers), printer id)
3. Response:
SUCCESS (code 200):
{result: true, message: [{...}, ...]}FAIL (code not 200):
{result: false, message: error_text}
18. Get users in the Workgroup
1. URL: /apiglobal/get_workgroup_users [POST Request]
2. Parameters:
session
workgroup_id (int)
3. Response:
SUCCESS (code 200):
{result: true, message: [{ "id":"int, user id", "email":"text, user email", "name":"text, firstname&lastname of user", "monthly_quota": null or int (user’s print quota), "balance":null or float (user’s balance)}, ...]}FAIL (code not 200):
{result: false, message: error_text}
19. Add user to Workgroup
1. URL: /apiglobal/add_user_to_workgroup [POST Request]
2. Parameters:
session
workgroup_id (int)
email (user’s email)
3. Response:
SUCCESS (code 200):
{result: true, message: [“user_id”: int (user id)]}FAIL (code not 200):
{result: false, message: error_text}
20. Delete the user from Workgroup
1. URL: /apiglobal/delete_user_from_workgroup [POST Request]
2. Parameters:
session
workgroup_id (int)
user_id (user’s id)
3. Response:
SUCCESS (code 200):
{result: true, message: []}FAIL (code not 200):
{result: false, message: error_text}
21. Get printer types used in the cloud (non-industrial, with printer parameters field)
1. URL: /apiglobal/get_printer_types_detailed [POST Request]
2. Parameters:
No parameters
3. Response:
SUCCESS (code 200):
{result: true, message: [{ id: int, description: text, printer_parameters: Json object (ex. {"x":"340","y":"340","z":"230","filament_diameter":"1.75","offset_x":"0","offset_y":"340"})}, ...]}FAIL (code not 200):
{result: false, message: error_text}
22. Get the custom report for organizational admins/moderators
1. URL: /apiglobal/get_custom_report [POST Request]
2. Parameters:
session
from (optional, string; Y-m-d date string, for ex 2019-06-01; default is today-31 days)
to (optional, string; Y-m-d date string, for ex 2019-06-01; default is today; max range for from-to is 365 days)
type (optional, string; type of response: json or CSV; default is CSV)
workgroups (optional, integer 1 or 0; add to response fields connected with Workgroups)
fields (optional, string of comma separated fields; all available fields: “job_id, printer_id, printer_name, printer_type, file_id, file_name, print_date, email, fname, lname, filament, cost, status, print_time, real_print_time, cancel_reason, cancel_details, started_by_email, feedback”)
all_fields (optional, integer 1 or 0; show all available fields or only fields that were selected in the organizational settings tab; default is 0; if you set this to 1 then “fields” parameter is ignored)
3. Response:
SUCCESS (code 200):
{"result":true,"message":[ ["Job ID","Printer ID","Printer Name","Printer Type","File ID","File Name","Print Date\/Time","Account Email","Filament","Material Cost","Status","Estimated Print Time","Real Print Time","Cancel Reason","Cancel Details","Feedback","Workgroup IDs","Workgroup Names","Workgroup Passwords"], ["int","int","text","text","int","text","text","text","float","float","text","text","text","text","text","text","int,int,...","text,text,...","text,text,..."],...]}FAIL (code not 200):
{result: false, message: error_text}
23. Get a camera list token (internal usage)
1. URL: /apiglobal/get_camera_list_token [POST Request]
2. Parameters:
session
printer_id (optional, int, printer id)
3. Response:
SUCCESS (code 200):
{result: true, message: { "token":"unique text token", "webcam_id": int (from 0), "rotate": boolean (true|false)}}FAIL (code not 200):
{result: false, message: error_text}
24. User login/registration using Google OAuth token id
1. URL: /apiglobal/google_login [POST Request]
2. Parameters:
token - text
3. Response:
SUCCESS, user login (code 200):
{result: true, message: {session: text, email: text}}SUCCESS, user registration (code 200):
{result: true, message: {session: text, gdpr_needed: true}}FAIL (code not 200):
{result: false, message: error_text}
25. Confirmation of GDPR flags and user registration
1. URL: /apiglobal/gdpr_registration [POST Request]
2. Parameters:
session - text (session from user registration with flag gdpr_needed: true)
gdpr1 - text, on|off (required, need to be “on”; confirmation about proceeding user email and IP address)
gdpr2 - text, optional, on|off (confirmation about using user’s personal data across the system)
cancel - text, optional (any non-empty value) - clear GDPR flag from session
3. Response:
SUCCESS (code 200):
{result: true, message: {session: text, email: text}}FAIL (code not 200):
{result: false, message: error_text}
26. Create organization user
1. URL: /apiglobal/create_organization_user [POST Request]
2. Parameters:
session
email (text) - email address of new user
gdpr: (integer, required) - GDPR access role
1 - confirmation about proceeding with user email and IP address;
3 - confirmation about proceeding with user email and IP address + confirmation about using user’s personal data across the system)
GDPR is the European General Data Protection Regulation (https://gdpr-info.eu/). 3DPrinterOS Cloud is a GDPR complaint that's why we need to get a permission from user to store his data (email, IP address, last name, first name) on registration
firstname (text, optional) - first name of new user
lastname (text, optional) - last name of new user
company (text, optional) - company of new user
access_role (integer, optional) - new user access role in the organization
0 - org member
1 - org admin
2 - Workgroup admin
3. Response:
SUCCESS (code 200):
{result: true, message: {}}FAIL (code not 200):
{result: false, message: error_text}
27. Get finished jobs report
1. URL: /apiglobal/get_finished_jobs_report [POST Request]
2. Parameters:
session
from (optional, string; Y-m-d date string, for ex 2019-06-01; default is today-31 days)
to (optional, string; Y-m-d date string, for ex 2019-06-01; default is today; max range for from-to is 365 days)
3. Response:
SUCCESS (code 200):
{"result": true, "message": [ { "email": "user@org.com", "firstname": "First name", "lastname": "Last name", "filename": "model_name.stl", "endtime": "2021-07-18 14:31:05" } ] }FAIL (code not 200):
{result: false, message: error_text}
28. File Slice Action [in development]
1. URL: /apiglobal/slice [POST Request]
2. Parameters:
session
file_id (required, integer, id of STL file)
slicer_id (optional, integer; list of variant provided below; default is 61 (Slicer 5))
profile (required, text json profile or array profile (object); the proper value could be obtained from the slice or slice_3 request in 3DPrinterOS Cloud - more detailed instructions are below)
add_print_job_to_printer_id (optional, integer; the printer ID to queue a sliced file on)
start_print_job (optional, will be taken into account if add_print_job_to_printer_id was set; could be 1, 0, true, false)
3. Response:
SUCCESS (code 200):
{"result":true,"message":{ "job_id":"appeng-job-id-uuid", "job_waiting":false, "running_jobs_limit":3, "output_file_id":integer}}FAIL (code not 200):
{result: false, message: error_text}
4. Details:
Available slicer_ids: 3 (Cloud Slicer), 48 (MakerBot Slicer), 60 (FormLabs Slicer), 51 (Slicer 3), 61 (Slicer 5), 62 (Bambu Lab Slicer - currently supports Bambu Lab X1, P1P, and X1 Carbon)
To get the proper profile for Cloud Slicer, Makerbot Slicer, or FormLabs Slicer, you could use the json from the Expert tab of the Slicer in Cloud.
To get the proper profile for Slicer 3/5, you will need to get it from the Slicing request (Chrome DevTools -> Network tab -> Execute any slicing with appropriate profile settings -> get the corresponding profile from /ajax/slice_3 request:
It could be copied with a left click and then a left double click to the corresponding area, so all the parts of json will be selected -> right click -> Copy (Note: “Copy value” will add extra encoding to the string, which is not suitable (for example it will replace the “ “(space) with + and so on))
To set up printing for the Bambu Slicer, please read this document.
29. Print File
1. URL: /apiglobal/print_file [POST Request]
2. Parameters:
session
file_id (required, integer, id of the GCODE file (or any other file type for Industrial/Virtual printer))
printer_id (required, integer, id of the printer)
only_queue (optional, integer; 0 or 1, if 0 or not set it will try to Start the job after it is added)
3. Response:
SUCCESS (code 200):
{"result":true,"message":{"job_id":"new print job id"}}FAIL (code not 200):
{result: false, message: error_text}
30. Start print job [in development]
1. URL: /apiglobal/job_start [POST Request]
2. Parameters:
session
job_id (required, integer, id of the print job)
3. Response:
SUCCESS (code 200):
{"result":true,"message":"Ok"}FAIL (code not 200):
{result: false, message: error_text}
31. Pause printer
1. URL: /apiglobal/job_pause [POST Request]
2. Parameters:
session
job_id (required, integer, id of the print job)
3. Response:
SUCCESS (code 200):
{"result":true,"message":"Ok"}FAIL (code not 200):
{result: false, message: error_text}
32. Unpause (resume) printer
1. URL: /apiglobal/job_unpause [POST Request]
2. Parameters:
session
job_id (required, integer, id of the print job)
3. Response:
SUCCESS (code 200):
{"result":true,"message":"Ok"}FAIL (code not 200):
{result: false, message: error_text}
33. Cancel print job
1. URL: /apiglobal/job_cancel [POST Request]
2. Parameters:
session
job_id (required, integer, id of the print job)
3. Response:
SUCCESS (code 200):
{"result":true,"message":"Ok"}FAIL (code not 200):
{result: false, message: error_text}
34. Update user settings
1. URL: /apiglobal/update_user_settings [POST Request]
2. Parameters:
session
user_id (required, integer, id of the user)
balance (optional, integer)
quota(optional, integer)
3. Response:
SUCCESS (code 200):
{"result":true,"message":"Ok"}FAIL (code not 200):
{result: false, message: error_text}
35. Clear Cloud’s emulated “Build Tray is clear” flag
1. URL: /apiglobal/printer_clear_build_tray [POST Request]
2. Parameters:
session
printer_id (required, integer, id of the printer)
is_clear (optional, string, "false|true"; default is "true" - Set bed is clear)
3. Response:
SUCCESS (code 200):
{"result":true,"message":"Ok"}FAIL (code not 200):
{result: false, message: error_text}