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
Get users in the Organization
Update (increase/decrease) users balances (only for Default (internal) balance logic)
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}
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" }}FAIL (code not 200):
{result: false, message: error_text}
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}
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) OR emails[] - list of user's emails
3. Response with "email" used:
SUCCESS (code 200):
{result: true, message: {"user_id": int (user id)}}FAIL (code not 200):
{result: false, message: error_text}
4. Response with "emails[]" used:
SUCCESS (code 200):
{result: true, message: {"notex": ["email",...], "otherorg": ["email",...], "notvalid": ["email",...], "errors": {"email": "Error message",...}}}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: Workgroup IDs, Workgroup Names, and Workgroup Passwords; default is 0; if user is in multiple Workgroups, then data in these fields are comma-separated)
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" + workgroup fields if "workgroups" parameter is set to 1: "workgroup_ids, workgroup_names, workgroup_passwords" + dynamic fields for Q&A questions if applicable: "question_%Question_DB_ID%")
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)
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)
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}
36. Get users in the Organization
1. URL: /apiglobal/get_org_users [POST Request]
2. Parameters:
session
user_id (optional, integer; filter user by id)
email (optional, text; filter user by email)
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), "ban": "text, t or f", "advanced": "text, t or f", "admin": "text, 0 - non admin, 1 - org admin, 2 - workgroup moderator"}, ...]}FAIL (code not 200):
{result: false, message: error_text}
37. Update (increase/decrease) users balances (only for Default (internal) balance logic)
1. URL: /apiglobal/update_users_balance [POST Request]
2. Parameters:
session
emails[] - list of emails
balance_update_amount (float val; if >0 increase user balance; if <0 decrease balance; in case if user has unlimited balance - no change is performed)
balance_update_note (text, optional; transaction description, maximum 128 characters; if omitted the default value is 'APIGlobal: Update user balance')
no_error_on_insufficient (0|1, optional, default is 0; takes effect only if balance_update_amount < 0. When set to "0" it will add email to "insufficient" list if the current user balance is less than wanted amount; when set to "1" it will not complain about insufficient balance - if user's balance is insufficient it will be set to 0 (if balance is already 0 or less - no changes))
3. Response:
SUCCESS (code 200):
{result: true, message: {"notex": ["email",...], "otherorg": ["email",...], "notvalid": ["email",...], "extbalance": ["email",...], "insufficient": ["email",...], "nullbalance": ["email",...], "errors": {"email": "Error message",...}}}FAIL (code not 200):
{result: false, message: error_text}