diff --git a/scripts/check_outdated.py b/scripts/check_outdated.py index f3accabda93..eaf71baf971 100644 --- a/scripts/check_outdated.py +++ b/scripts/check_outdated.py @@ -1,17 +1,17 @@ import os import re -from settings import ENDPOINTS_DIR - +ENDPOINTS_DIR = "" DOCUMENTATION_DIR = os.path.join(os.path.dirname(__file__), "../source/includes") -def get_all_endpoints(): +def get_all_endpoints(with_disabled=False): endpoints = [] for root, dirs, files in os.walk(ENDPOINTS_DIR): for file in files: - with open(os.path.join(root, file), 'r') as f: - if re.search(r"public bool \$api_disabled = true;", f.read()): - continue + if not with_disabled: + with open(os.path.join(root, file), 'r') as f: + if re.search(r"public *bool *\$api_disabled *= true;", f.read()): + continue endpoints.append(root.split(ENDPOINTS_DIR)[1] + "/" + file[:-4]) @@ -25,12 +25,12 @@ def get_all_documented_endpoints(): file_cat = file[1:-3] with open(os.path.join(DOCUMENTATION_DIR, file), 'r') as f: for line in f.readlines(): - match = re.match(r"curl https:\/\/api\.simplyprint\.io\/\{id\}(.*?)(\?| \\).*$", line) + match = re.match(r"(?:curl)?.*https:\/\/api\.simplyprint\.io\/\{id\}(.*?)(\?| \\).*$", line) if not match: continue - endpoints.append(match.group(1)) + endpoints.append(match.group(1).replace("\"", "")) endpoints.sort() return endpoints diff --git a/source/includes/_account.md b/source/includes/_account.md index 6c9da65ee04..f2437415e04 100644 --- a/source/includes/_account.md +++ b/source/includes/_account.md @@ -53,8 +53,8 @@ curl https://api.simplyprint.io/{id}/account/settings/groups/Create \ | Required permissions | -| --------------------- | -| `ORG_RANK_MANAGEMENT` | +|-----------------------| +| `org_rank_management` | This endpoint creates a new group in the company. @@ -63,7 +63,7 @@ This endpoint creates a new group in the company. `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. | @@ -73,7 +73,7 @@ This endpoint creates a new group in the company. ### 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. | @@ -97,7 +97,7 @@ curl https://api.simplyprint.io/{id}/account/settings/groups/Update \ "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, + "sort_order": 3 } ] } @@ -129,8 +129,8 @@ curl https://api.simplyprint.io/{id}/account/settings/groups/Update \ | Required permissions | -| --------------------- | -| `ORG_RANK_MANAGEMENT` | +|-----------------------| +| `org_rank_management` | This endpoint updates the groups in the company. @@ -139,7 +139,7 @@ This endpoint updates the groups in the company. `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. | @@ -150,7 +150,7 @@ This endpoint updates the groups in the company. ### 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. | @@ -167,7 +167,6 @@ This endpoint updates the groups in the company. ```shell curl https://api.simplyprint.io/{id}/account/GetGroups \ - -X GET \ -H 'accept: application/json' \ -H 'X-API-KEY: {API_KEY}' ``` @@ -200,8 +199,8 @@ curl https://api.simplyprint.io/{id}/account/GetGroups \ | Required permissions | -| --------------------- | -| `ORG_RANK_MANAGEMENT` | +|-----------------------| +| `org_rank_management` | This endpoint returns a list of groups that exist in the company. @@ -212,7 +211,7 @@ This endpoint returns a list of groups that exist in the company. ### 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. | @@ -242,7 +241,7 @@ curl https://api.simplyprint.io/{id}/account/settings/groups/Delete \ ```json { "status": true, - "message": null, + "message": null } ``` @@ -251,22 +250,22 @@ curl https://api.simplyprint.io/{id}/account/settings/groups/Delete \ | Required permissions | -| --------------------- | -| `ORG_RANK_MANAGEMENT` | +|-----------------------| +| `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. | @@ -283,8 +282,16 @@ curl https://api.simplyprint.io/{id}/account/GetStatistics \ ```json { - "users": [1234, 1235, 1945], - "printers": [1234, 1235, 1945], + "users": [ + 1234, + 1235, + 1945 + ], + "printers": [ + 1234, + 1235, + 1945 + ], "start_date": "1677629786", "end_date": "1677629786" } @@ -294,46 +301,46 @@ curl https://api.simplyprint.io/{id}/account/GetStatistics \ ```json { - "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 - }, - ... - ] - } + "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 + }, + ... + ] + } } ``` @@ -348,7 +355,7 @@ This endpoint returns statistics for the user / company. `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. | @@ -357,7 +364,7 @@ This endpoint returns statistics for the user / company. ### Response | Parameter | Type | Description | -| ---------------------------------------- | ------- | ---------------------------------------- | +|------------------------------------------|---------|------------------------------------------| | `status` | boolean | True if the request was successful. | | `message` | string | Error message if `status` is false. | | `data` | object | Statistics object. | diff --git a/source/includes/_api_files.md b/source/includes/_api_files.md index 7a8d035d88e..69890cfa0ae 100644 --- a/source/includes/_api_files.md +++ b/source/includes/_api_files.md @@ -1,6 +1,8 @@ # 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. +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 @@ -8,7 +10,7 @@ The base URL for the SimplyPrint Files API is `https://files.simplyprint.io/{id} This endpoint requires the Print Farm plan. -`POST {id}/files/Upload` +`POST /{id}/files/Upload` > Example request to upload a file less than 100MB @@ -18,17 +20,18 @@ curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \ -H "X-API-KEY: {API_KEY}" \ -F "file=@/path/to/file.gcode" ``` + > Success response ```json { - "status":true, - "message": null, - "file": { - "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd", - "name": "file.gcode", - "size": 13439 - } + "status": true, + "message": null, + "file": { + "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd", + "name": "file.gcode", + "size": 13439 + } } ``` @@ -41,13 +44,14 @@ curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \ -F "file=@/path/to/part1.3mf" -F "totalSize=3352316" ``` + > Success response with continueToken ```json { - "status":true, - "message":null, - "continueToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJ0eXBlIjoiYWN0ao9uX3Rva2VuIiwiYWN0aW9uIjoiZmlsZV9jb250aW51ZV91cGxvYWQiLCJ1c2VyIjo2OTc2LCJjb21wYW55IjoyLCJkYXRhIja7ImJ1Y2tldEhhc2giOiI0MGQ2MzgwNmQwYWUxODhkNjc5YzY0NjA0M2RiYjUxMTc0NTViNTc1NjNlODEzZDc2MGRjMTJkMzVaYjdmY2Y0IiwidG90YWxTaXplIjoxNjc2MTU4NH0sImlhdCI6MTcyNTU2MjEzMywiZXhwIjoxNzI1NjQ4NTMzfQ.9qyNyx9A4Ox_6GrFSxXpxlpLcAKaSr8ln84X3yuWdhT_2O3L8-lGWaXAbQk9VvR-3pu1-a9p40amnt6Fghy49InjzCfNMRp-6-Ft_uMRf6PbmcCCrksvRxNP38ImoXy6" + "status": true, + "message": null, + "continueToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzM4NCJ9.eyJ0eXBlIjoiYWN0ao9uX3Rva2VuIiwiYWN0aW9uIjoiZmlsZV9jb250aW51ZV91cGxvYWQiLCJ1c2VyIjo2OTc2LCJjb21wYW55IjoyLCJkYXRhIja7ImJ1Y2tldEhhc2giOiI0MGQ2MzgwNmQwYWUxODhkNjc5YzY0NjA0M2RiYjUxMTc0NTViNTc1NjNlODEzZDc2MGRjMTJkMzVaYjdmY2Y0IiwidG90YWxTaXplIjoxNjc2MTU4NH0sImlhdCI6MTcyNTU2MjEzMywiZXhwIjoxNzI1NjQ4NTMzfQ.9qyNyx9A4Ox_6GrFSxXpxlpLcAKaSr8ln84X3yuWdhT_2O3L8-lGWaXAbQk9VvR-3pu1-a9p40amnt6Fghy49InjzCfNMRp-6-Ft_uMRf6PbmcCCrksvRxNP38ImoXy6" } ``` @@ -65,33 +69,33 @@ curl -X POST "https://files.simplyprint.io/{id}/files/Upload" \ ```json { - "status":true, - "message":null, - "file": { - "id": "f568ead4bbc2d881efc8a9a05f3bd585334cd8c662347ba2dfad7250176b0abd", - "name": "part1.3mf", - "size": 3352316 - } + "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 | +| 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 | +| 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 | diff --git a/source/includes/_courses.md b/source/includes/_courses.md new file mode 100644 index 00000000000..25a4417f26d --- /dev/null +++ b/source/includes/_courses.md @@ -0,0 +1,274 @@ +# Courses + + + +## Get course + +```shell +curl https://api.simplyprint.io/{id}/courses/GetCourse?id=123 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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`. | diff --git a/source/includes/_custom_fields.md b/source/includes/_custom_fields.md new file mode 100644 index 00000000000..0aa9524dadf --- /dev/null +++ b/source/includes/_custom_fields.md @@ -0,0 +1,338 @@ +# Custom Fields + + + +Custom Fields allow you to add your own data-fields inside SimplyPrint. + +[Read more about Custom Fields on our Helpdesk](https://help.simplyprint.io/en/article/all-about-the-custom-fields-feature-4dd5if/) + +## List custom fields + + + +| Required permissions | +|------------------------| +| `custom_fields_manage` | + +`POST /{id}/custom_fields/Get` + +> Example request + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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: + +```json +{ + "string": "1234567890" +} +``` + +> A number field would have a value like this: + +```json +{ + "number": 1234567890 +} +``` + +> A date field would have a value like this: + +```json +{ + "date": "2024-09-07" +} +``` + +> A select field would have a value like this: + +```json +{ + "string": "Selected option" +} +``` + +> A multi-select field would have a value like this: + +```json +{ + "options": [ + "Option 1", + "Option 2" + ] +} +``` diff --git a/source/includes/_errors.md b/source/includes/_errors.md index 7260ecfdd5e..0a7205ca52e 100644 --- a/source/includes/_errors.md +++ b/source/includes/_errors.md @@ -3,7 +3,7 @@ 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. | @@ -29,6 +29,6 @@ The SimplyPrint API uses the following HTTP error codes: 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 | diff --git a/source/includes/_filament.md b/source/includes/_filament.md index 8f523fa678e..9ae4c19b14e 100644 --- a/source/includes/_filament.md +++ b/source/includes/_filament.md @@ -72,7 +72,7 @@ This endpoint returns a list of all filaments as well as filament types and bran ### 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) | @@ -171,11 +171,12 @@ curl https://api.simplyprint.io/{id}/filament/Create \ 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. +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` | +|----------------------| +| `create_filament` | ### Request @@ -184,13 +185,13 @@ To update existing filament, you need to provide a `fid` query parameter, which #### 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. | @@ -222,7 +223,7 @@ To update existing filament, you need to provide a `fid` query parameter, which ### 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. | @@ -248,21 +249,21 @@ curl https://api.simplyprint.io/{id}/filament/Delete?fid=4519 \ This endpoint deletes a filament specified by the `fid` parameter. | Required permissions | -| -------------------- | -| `CREATE_FILAMENT` | +|----------------------| +| `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. | @@ -279,10 +280,10 @@ curl https://api.simplyprint.io/{id}/filament/Assign?pid=5123&fid=21812,31253 \ ```json { - "extruder": { - "21812": 0, - "31253": 1 - } + "extruder": { + "21812": 0, + "31253": 1 + } } ``` @@ -298,8 +299,8 @@ curl https://api.simplyprint.io/{id}/filament/Assign?pid=5123&fid=21812,31253 \ This endpoint assigns filament(s) to a printer. | Required permissions | -| -------------------- | -| `CHANGE_FILAMENT` | +|----------------------| +| `change_filament` | ### Request @@ -310,21 +311,21 @@ 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. | @@ -348,20 +349,20 @@ curl https://api.simplyprint.io/{id}/filament/Unassign?fid=21812 \ This endpoint unassigns a filament from a printer by filament id. | Required permissions | -| -------------------- | -| `CHANGE_FILAMENT` | +|----------------------| +| `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. | diff --git a/source/includes/_files.md b/source/includes/_files.md index 6c1ffa9a7ff..af659ae5521 100644 --- a/source/includes/_files.md +++ b/source/includes/_files.md @@ -8,20 +8,18 @@ `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](#api-files) +| 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](#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 | - +| 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 | ```shell curl -X POST https://api.simplyprint.io/{id}/files/Upload?folder=5290 \ @@ -34,9 +32,9 @@ curl -X POST https://api.simplyprint.io/{id}/files/Upload?folder=5290 \ ```json { - "status":true, - "message":null, - "id":"6f7d79212f384c6b8eae2811c37d9338" + "status": true, + "message": null, + "id": "6f7d79212f384c6b8eae2811c37d9338" } ``` @@ -72,7 +70,7 @@ curl https://api.simplyprint.io/{id}/files/GetFiles?f=123&search=benchy \ "user_id": 123, "thumbnail": 1, "folder": 0, - "user": 123, + "user": 123 }, { "id": "e82ab9e1cc3c20850d94d5cf539390c0", @@ -105,44 +103,56 @@ curl https://api.simplyprint.io/{id}/files/GetFiles?f=123&search=benchy \ "ext": 0, "type": 123, "color": "Green", - "hex":"#4CAF50" + "hex": "#4CAF50" } ], - "custom": [1, 2, 3] + "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 - } + "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, @@ -176,7 +186,7 @@ This endpoint returns a list of files and folders in a given folder. If no folde `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`. | @@ -185,7 +195,7 @@ This endpoint returns a list of files and folders in a given folder. If no folde ### 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. | @@ -219,14 +229,14 @@ This endpoint moves one or more files to a given folder. `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. | @@ -271,13 +281,13 @@ This endpoint returns details about a given folder. `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. | @@ -316,13 +326,13 @@ Also, folders cannot be moved into themselves. `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. | diff --git a/source/includes/_jobs.md b/source/includes/_jobs.md index 58af22beced..a31e76061dc 100644 --- a/source/includes/_jobs.md +++ b/source/includes/_jobs.md @@ -1,6 +1,6 @@ # Print Jobs -## Get Print Jobs +## Get print jobs ```shell curl https://api.simplyprint.io/{id}/jobs/GetPaginatedPrintJobs \ @@ -15,8 +15,13 @@ curl https://api.simplyprint.io/{id}/jobs/GetPaginatedPrintJobs \ { "page": 1, "page_size": 10, - "printer_ids": [385], - "status": ["cancelled", "finished"], + "printer_ids": [ + 385 + ], + "status": [ + "cancelled", + "finished" + ], "start_date": "2023-02-28" } ``` @@ -38,6 +43,8 @@ curl https://api.simplyprint.io/{id}/jobs/GetPaginatedPrintJobs \ "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, @@ -55,12 +62,12 @@ curl https://api.simplyprint.io/{id}/jobs/GetPaginatedPrintJobs \ }, { "id": 2, - "label":"Material markup", + "label": "Material markup", "cost": null }, { "id": 3, - "label":"Machine run time cost", + "label": "Machine run time cost", "cost": null }, { @@ -79,7 +86,15 @@ curl https://api.simplyprint.io/{id}/jobs/GetPaginatedPrintJobs \ "id": 1234, "user": 51, "queueNum": 3 - } + }, + "customFields": [ + { + "id": "student_id", + "value": { + "string": "1234567890" + } + } + ] }, ... ], @@ -94,7 +109,7 @@ Get paginated data about ongoing or finished print jobs. `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. | @@ -106,28 +121,151 @@ Get paginated data about ongoing or finished print jobs. ### 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 | The user id of the user who started the job. | -| `data[].printer` | integer | The printer id that was used to print the job. | -| `data[].filament` | string | The filament usage. JSON encoded string with usage per extruder. | -| `data[].filUsage` | integer | The filament usage in mm. | -| `data[].filUsageGram` | integer | The filament usage in grams. | -| `data[].currentPercentage` | integer | The current percentage of the job. | -| `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. | +| 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 + +```shell +curl https://api.simplyprint.io/{id}/jobs/GetDetails \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' \ + -d '{ + "id": "job_id" + }' +``` + +> Success response + +```json +{ + "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. | diff --git a/source/includes/_partner.md b/source/includes/_partner.md new file mode 100644 index 00000000000..323b5ef7122 --- /dev/null +++ b/source/includes/_partner.md @@ -0,0 +1,532 @@ +# Partner + + + +## Get companies + +```shell +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 + +```json +{ + "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 + +```shell +curl https://api.simplyprint.io/{id}/partner/GetCompany?company=123&initial=true \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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 + +```shell +curl https://api.simplyprint.io/{id}/partner/GetOverviewStats \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +curl -X POST https://api.simplyprint.io/{id}/partner/DeleteCompany?company=123 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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`. | + +## Validate printer (partner-wide printer search) + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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`. | + +## Validate filament (partner-wide filament search) + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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`. | diff --git a/source/includes/_permissions_scopes.md b/source/includes/_permissions_scopes.md index 1d528d796d8..027e0bd4e3c 100644 --- a/source/includes/_permissions_scopes.md +++ b/source/includes/_permissions_scopes.md @@ -2,29 +2,95 @@ ## Company permissions -These permissions are used to control access within a company. The permissions are tied to the user groups within the company. +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 | -| ------------------------ | --------------------------------------------------------------- | -| `PRINTER_EDIT` | "Allow to create, edit and delete printers" | -| `CREATE_FILAMENT` | "Allow creating, editing and deleting filament spools" | -| `CHANGE_FILAMENT` | "Allow change of filament" | -| `PRINT_QUEUE_REMOVE_ALL` | "Allow deletion of other user's print queue items" | -| `ORG_RANK_MANAGEMENT` | "Allow to create, edit, delete and change order of user groups" | -| `VIEW_USERS` | "Allow overview of users in organization" | -| `INVITE_USERS` | "Allow invite of other users" | -| `DELETE_USER` | "Allow delete users" | -| `SLICER_ORG_PROFILES` | "Allow to create and edit organisation slicer profiles" | -| `EDIT_TAGS` | "Allow user to create, update and delete tags" | +| 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 | diff --git a/source/includes/_printer_groups.md b/source/includes/_printer_groups.md new file mode 100644 index 00000000000..65d0afbf4c1 --- /dev/null +++ b/source/includes/_printer_groups.md @@ -0,0 +1,207 @@ +# Printer Groups + +## Get groups + +```shell +curl https://api.simplyprint.io/{id}/groups/Get \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' \ +``` + +> Success response + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +curl https://api.simplyprint.io/{id}/groups/Delete?group=123 \ + -X POST \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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 + +```shell +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 + +```json +{ + "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`. | diff --git a/source/includes/_printers.md b/source/includes/_printers.md index a39ceaacbd7..dba81a8aa36 100644 --- a/source/includes/_printers.md +++ b/source/includes/_printers.md @@ -142,10 +142,14 @@ curl https://api.simplyprint.io/{id}/printers/Get \ "ext": 0, "type": 123, "color": "Green", - "hex":"#4CAF50" + "hex": "#4CAF50" } ], - "custom": [1, 2, 3] + "custom": [ + 1, + 2, + 3 + ] } }, ... @@ -162,13 +166,13 @@ This endpoint returns a list of printers based on the given parameters. #### 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. | @@ -178,7 +182,7 @@ This endpoint returns a list of printers based on the given parameters. 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). | @@ -229,7 +233,10 @@ curl https://api.simplyprint.io/{id}/printers/actions/CreateJob?pid=1234&filesys ```json { - "pid": [1234, 1235], + "pid": [ + 1234, + 1235 + ], "filesystem": "196a1dd0b93a66c19192a39fa4c16e71" } ``` @@ -278,7 +285,7 @@ curl https://api.simplyprint.io/{id}/printers/actions/CreateJob?pid=1234&filesys }, "printers": [ 1234, - 1235 + 1235 ], "queued": false, "cost": [ @@ -327,28 +334,33 @@ curl https://api.simplyprint.io/{id}/printers/actions/CreateJob?pid=1234&filesys You can only upload files through the API using API Files -This endpoint can be used to create a print job for one or more printers. The printers have to be in the `operational` state. +This endpoint can be used to create a print job for one or more printers. The printers have to be in the `operational` +state. ### Request `POST /{id}/printers/actions/CreateJob` -To start a print job you must either specify a `filesystem` ID, a `queue_file` ID file or set `next_queue_item` to true. +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. | -| `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](#api-files) - used to start a file without adding it as a queue item or user file. +| 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](#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: }` where the `` is a [Custom Field Submission Value](#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. +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** | @@ -358,7 +370,7 @@ You can specify these parameters if `next_queue_item` is `true`. Note that you c ### 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. | @@ -396,13 +408,13 @@ This endpoint can be used to pause one or multiple print jobs. The printers have #### 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. | @@ -431,13 +443,13 @@ curl https://api.simplyprint.io/{id}/printers/actions/Resume?pid=1234 \ #### 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. | @@ -469,10 +481,11 @@ curl https://api.simplyprint.io/{id}/printers/actions/Cancel?pid=1234 \ ``` | Required permission | Description | -| ---------------------- | ------------------------------------------------------------------------------------------- | -| `CANCEL_OTHERS_PRINTS` | Need permission to cancel other users' prints if the print job was started by another user. | +|------------------------|---------------------------------------------------------------------------------------------| +| `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. +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 @@ -481,20 +494,20 @@ This endpoint can be used to cancel one or multiple print jobs. The printers hav #### 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](#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. | @@ -534,20 +547,20 @@ This endpoint can be used to clear the print bed of a printer. #### 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. | @@ -569,34 +582,406 @@ curl https://api.simplyprint.io/{id}/printers/Delete?pid=1234&just_connection=1 ``` | Required permissions | -| -------------------- | -| `PRINTER_EDIT` | +|----------------------| +| `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. +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` | + +```shell +curl https://api.simplyprint.io/{id}/printers/OneClickPrint?pIds=1234,1235 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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` | + +```shell +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 + +```json +{ + "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` | + +```shell +curl https://api.simplyprint.io/{id}/printers/autoprint/CheckState \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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` | + +```shell +curl https://api.simplyprint.io/{id}/printers/autoprint/GetAutoPrintSettings \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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` | + +```shell +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 + +```json +{ + "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` | + + + +```shell +curl https://api.simplyprint.io/{id}/printers/autoprint/GetGcodeTemplates \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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` | + +```shell +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 + +```json +{ + "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 | +| 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 | diff --git a/source/includes/_queue.md b/source/includes/_queue.md index a666c3403a6..54dbd64bfc2 100644 --- a/source/includes/_queue.md +++ b/source/includes/_queue.md @@ -37,25 +37,32 @@ curl https://api.simplyprint.io/{id}/queue/AddItem \ You can only upload files through the API using API Files -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. +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](#update-queue-item) after it has been added to the queue. +**Note:** if you want to specify which printer/printer type/printer model the print job should be assigned, you +can [edit the print job](#update-queue-item) after it has been added to the queue. ### Request `POST /{id}/queue/AddItem` -| Parameter | Type | Required | Description | -| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | -| `filesystem` | string | no | The [filesystem](#files) 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](#api-files) - use this to add a file uploaded via the API. | +| Parameter | Type | Required | Description | +|-----------------|---------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `filesystem` | string | no | The [filesystem](#files) 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](#api-files) - use this to add a file uploaded via the API. | +| `tags` | object | no | Tags to assign. Only send [nozzle](#assign-nozzle-size-tag) body, [material](#assign-material-tag) body or [custom](#assign-custom-tag) 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: }` where the `` is a [Custom Field Submission Value](#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 | @@ -107,7 +114,15 @@ curl https://api.simplyprint.io/{id}/queue/GetNextItems?p=1234 \ "missed": 0, "name": "Benchy.gcode", "printed": 2, - "left": 1 + "left": 1, + "customFields": [ + { + "id": "student_id", + "value": { + "string": "1234567890" + } + } + ] } ] } @@ -144,7 +159,8 @@ curl https://api.simplyprint.io/{id}/queue/GetNextItems?p=1234 \ This endpoint requires the Print Farm plan. -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. +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 @@ -153,13 +169,13 @@ This endpoint gets the next item in the queue for the specified printer. The nex #### 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** | @@ -171,7 +187,7 @@ This endpoint gets the next item in the queue for the specified printer. The nex ### 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. | @@ -188,6 +204,124 @@ This endpoint gets the next item in the queue for the specified printer. The nex | `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 + +```shell +curl https://api.simplyprint.io/{id}/queue/GetItem?id=1234 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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 ```shell @@ -269,11 +403,23 @@ curl https://api.simplyprint.io/{id}/queue/GetItems?p=1234 \ "ext": 0, "type": 123, "color": "Green", - "hex":"#4CAF50" + "hex": "#4CAF50" } ], - "custom": [1, 2, 3] - } + "custom": [ + 1, + 2, + 3 + ] + }, + "customFields": [ + { + "id": "student_id", + "value": { + "string": "1234567890" + } + } + ] } ] }, @@ -285,7 +431,7 @@ curl https://api.simplyprint.io/{id}/queue/GetItems?p=1234 \ "extensions": [ "gcode", "gco", - "stl", + "stl" ], "sort_order": 0 }, @@ -298,6 +444,10 @@ curl https://api.simplyprint.io/{id}/queue/GetItems?p=1234 \ This endpoint requires the Pro plan. +| Required permissions | +|----------------------| +| `print_queue` | + This endpoint returns the queue for the specified or all printers. ### Request @@ -305,14 +455,14 @@ This endpoint returns the queue for the specified or all printers. `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. | @@ -398,6 +548,10 @@ curl https://api.simplyprint.io/{id}/queue/UpdateItem?job=1234 \ This endpoint requires the Print Farm plan. +| Required permissions | +|----------------------| +| `print_queue` | + This endpoint updates the queue item with the specified id. ### Request @@ -407,13 +561,13 @@ This endpoint updates the queue item with the specified id. #### 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. | @@ -423,7 +577,7 @@ This endpoint updates the queue item with the specified id. ### Response | Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | +|-----------|---------|--------------------------------------------------------| | `status` | boolean | True if the request was successful. | | `message` | string | Success message or error message if `status` is false. | @@ -448,6 +602,10 @@ curl https://api.simplyprint.io/{id}/queue/DeleteItem?job=1234 \ This endpoint requires the Print Farm plan. +| Required permissions | +|----------------------| +| `print_queue` | + This endpoint deletes the queue item with the specified id. ### Request @@ -455,13 +613,13 @@ This endpoint deletes the queue item with the specified id. `? /{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. | @@ -477,8 +635,8 @@ curl https://api.simplyprint.io/{id}/queue/SetOrder?job=1234&from=0&to=1 \ ```json { - "success": true, - "message": null + "success": true, + "message": null } ``` @@ -486,6 +644,12 @@ curl https://api.simplyprint.io/{id}/queue/SetOrder?job=1234&from=0&to=1 \ This endpoint requires the Print Farm plan. +| 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 @@ -493,7 +657,7 @@ This endpoint changes the order of the queue items by moving the queue item with `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. | @@ -501,7 +665,7 @@ This endpoint changes the order of the queue items by moving the queue item with ### Response | Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------- | +|-----------|---------|---------------------------------------------------------| | `success` | boolean | True if the request was successful. | | `message` | string | Success message or error message if `success` is false. | @@ -527,8 +691,9 @@ curl https://api.simplyprint.io/{id}/queue/EmptyQueue \ | Required Permissions | -| ------------------------ | -| `PRINT_QUEUE_REMOVE_ALL` | +|--------------------------| +| `print_queue` | +| `print_queue_remove_all` | This endpoint empties the queue. @@ -537,12 +702,263 @@ This endpoint empties the queue. `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` | + +```shell +curl https://api.simplyprint.io/{id}/queue/ReviveItem?job=1234 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' \ +``` + +> Success response + +```json +{ + "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` | + +```shell +curl https://api.simplyprint.io/{id}/queue/groups/Get \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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` | + +```shell +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 + +```json +{ + "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` | + +```shell +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 + +```json +{ + "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` | + +```shell +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 + +```json +{ + "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`. | diff --git a/source/includes/_schools.md b/source/includes/_schools.md new file mode 100644 index 00000000000..4dec8b8ed8e --- /dev/null +++ b/source/includes/_schools.md @@ -0,0 +1,143 @@ +# Schools + +## List classes + + + +`GET /{id}/account/settings/school/classes/GetClasses` + +> Example request + +```shell +curl https://api.simplyprint.io/{id}/account/settings/school/classes/GetClasses \ +-H 'accept: application/json' \ +-H 'X-API-KEY: {API_KEY}' +``` + +> Example response + +```json +{ + "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 + +```json +{ + "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. | diff --git a/source/includes/_slicer.md b/source/includes/_slicer.md index dc061ff7c90..7b5ad27d678 100644 --- a/source/includes/_slicer.md +++ b/source/includes/_slicer.md @@ -3,7 +3,7 @@ ## List Slicer Profiles ```shell -curl -X GET https://api.simplyprint.io/{id}/slicer/ListProfiles \ +curl https://api.simplyprint.io/{id}/slicer/ListProfiles \ -H 'accept: application/json' \ -H 'X-API-KEY: {API_KEY}' ``` @@ -25,7 +25,8 @@ curl -X GET https://api.simplyprint.io/{id}/slicer/ListProfiles \ } ``` -This endpoint returns a list overview of slicer profiles that the user has access to. Includes personal and company profiles. +This endpoint returns a list overview of slicer profiles that the user has access to. Includes personal and company +profiles. ### Request @@ -34,7 +35,7 @@ This endpoint returns a list overview of slicer profiles that the user has acces ### 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. | @@ -130,13 +131,13 @@ This endpoint can be used to get a slicer profile by its ID. This includes the s `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. | @@ -159,7 +160,7 @@ TODO ## Delete Slicer Profile ```shell -curl -X GET https://api.simplyprint.io/{id}/slicer/DeleteProfile?id=1234 \ +curl https://api.simplyprint.io/{id}/slicer/DeleteProfile?id=1234 \ -H 'accept: application/json' \ -H 'X-API-KEY: {API_KEY}' ``` @@ -174,8 +175,8 @@ curl -X GET https://api.simplyprint.io/{id}/slicer/DeleteProfile?id=1234 \ ``` | Required permissions | Description | -| --------------------- | --------------------------------------- | -| `SLICER_ORG_PROFILES` | If the profile is owned by the company. | +|-----------------------|-----------------------------------------| +| `slicer_org_profiles` | If the profile is owned by the company. | This endpoint can be used to delete a slicer profile by its ID. @@ -184,12 +185,12 @@ This endpoint can be used to delete a slicer profile by its ID. `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. | diff --git a/source/includes/_tags.md b/source/includes/_tags.md index a769bbfd82c..484a2287225 100644 --- a/source/includes/_tags.md +++ b/source/includes/_tags.md @@ -13,7 +13,7 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Create \ ```json { "name": "My Custom Tag", - "badge": "success", + "badge": "success" } ``` @@ -33,13 +33,13 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Create \ "printers": 1, "printer_groups": 0, "files": 2, - "queue_items": 4, + "queue_items": 4 } }, { "id": 2, "name": "My Custom Tag", - "badge": "success", + "badge": "success" } ] } @@ -50,8 +50,8 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Create \ | Required permissions | -| -------------------- | -| `EDIT_TAGS` | +|----------------------| +| `edit_tags` | This endpoint creates or updates a custom tag. @@ -60,7 +60,7 @@ This endpoint creates or updates a custom tag. `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](#colors) section for a list of available colors. | @@ -68,7 +68,7 @@ This endpoint creates or updates a custom tag. ### 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. | @@ -101,7 +101,7 @@ curl https://api.simplyprint.io/{id}/tags/Get?id=2 \ "tag": { "id": 2, "name": "My Custom Tag", - "badge": "success", + "badge": "success" } } ``` @@ -129,13 +129,13 @@ curl https://api.simplyprint.io/{id}/tags/Get \ "printers": 1, "printer_groups": 0, "files": 2, - "queue_items": 4, + "queue_items": 4 } }, { "id": 2, "name": "My Custom Tag", - "badge": "success", + "badge": "success" } ] } @@ -152,13 +152,13 @@ This endpoint gets a single tag or all tags. `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. | @@ -192,7 +192,7 @@ curl https://api.simplyprint.io/{id}/tags/Delete?id=2 \ "printers": 1, "printer_groups": 0, "files": 2, - "queue_items": 4, + "queue_items": 4 } } ] @@ -204,8 +204,8 @@ curl https://api.simplyprint.io/{id}/tags/Delete?id=2 \ | Required permissions | -| -------------------- | -| `EDIT_TAGS` | +|----------------------| +| `edit_tags` | This endpoint deletes a custom tag. @@ -214,13 +214,13 @@ This endpoint deletes a custom tag. `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. | @@ -249,7 +249,7 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Assign \ ```json { "status": true, - "message": null, + "message": null } ``` @@ -262,7 +262,7 @@ Please note that to assign a tag to a printer, you need the `EDIT_PRINTER` permi `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. | @@ -271,7 +271,7 @@ Please note that to assign a tag to a printer, you need the `EDIT_PRINTER` permi ### Response | Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | +|-----------|---------|--------------------------------------------------------| | `status` | boolean | True if the request was successful. | | `message` | string | Success message or error message if `status` is false. | @@ -306,7 +306,7 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Assign \ ```json { "status": true, - "message": null, + "message": null } ``` @@ -319,7 +319,7 @@ Please note that to assign a tag to a printer, you need the `EDIT_PRINTER` permi `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. | @@ -332,7 +332,7 @@ Please note that to assign a tag to a printer, you need the `EDIT_PRINTER` permi ### Response | Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | +|-----------|---------|--------------------------------------------------------| | `status` | boolean | True if the request was successful. | | `message` | string | Success message or error message if `status` is false. | @@ -360,7 +360,7 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Assign \ ```json { "status": true, - "message": null, + "message": null } ``` @@ -377,7 +377,7 @@ Please note that to assign a tag to a printer, you need the `EDIT_PRINTER` permi `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. | @@ -386,7 +386,7 @@ Please note that to assign a tag to a printer, you need the `EDIT_PRINTER` permi ### Response | Parameter | Type | Description | -| --------- | ------- | ------------------------------------------------------ | +|-----------|---------|--------------------------------------------------------| | `status` | boolean | True if the request was successful. | | `message` | string | Success message or error message if `status` is false. | @@ -413,7 +413,7 @@ curl -X POST https://api.simplyprint.io/{id}/tags/Detach \ ```json { "status": true, - "message": null, + "message": null } ``` @@ -430,7 +430,7 @@ Please note that to detach a tag from a printer, you need the `EDIT_PRINTER` per `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. | @@ -438,14 +438,14 @@ Please note that to detach a tag from a printer, you need the `EDIT_PRINTER` per ### 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 | diff --git a/source/includes/_users.md b/source/includes/_users.md index a8d848fa58f..45cb97924cc 100644 --- a/source/includes/_users.md +++ b/source/includes/_users.md @@ -13,12 +13,12 @@ curl https://api.simplyprint.io/{id}/users/GetPaginatedUsers \ ```json { - "page": 1, - "page_size": 10, - "approved": true, - "search": "John Doe", - "sort_id": 1, - "sort_dir": "asc" + "page": 1, + "page_size": 10, + "approved": true, + "search": "John Doe", + "sort_id": 1, + "sort_dir": "asc" } ``` @@ -26,25 +26,30 @@ curl https://api.simplyprint.io/{id}/users/GetPaginatedUsers \ ```json { - "status": true, - "message": null, - "data": [ - { - "id": 1234, - "relation_id": 4321, - "name": "John Doe", - "email_confirmed": true, - "email": "johndoe@example.com", - "phone": "", - "relation_created_at": "2022-07-28 23:30:14", - "last_online": "2023-03-02 15:44:44", - "approved_at": "2022-07-29 11:14:52", - "org_account": false, - "total_prints": 68, - "rank": 185 - } - ], - "page_amount": 1 + "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 } ``` @@ -53,53 +58,47 @@ curl https://api.simplyprint.io/{id}/users/GetPaginatedUsers \ | Required permissions | -| -------------------- | -| `VIEW_USERS` | +|----------------------| +| `view_users` | ### Request `POST /{id}/users/GetPaginatedUsers` | Parameter | Type | Required | Description | -| ----------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------- | +|-------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------| | `page` | integer | yes | The page number to retrieve. | | `page_size` | integer | yes | The number of users to retrieve per page. | | `approved` | boolean | no | If true, only approved users will be returned. If false, only pending users will be returned.
**Defaults to true** | | `search` | string | no | A search string to filter the users by. Searches for name, email and phone number. | -| `sort_id` | integer | no | Which field to sort by. See [Sort IDs](#sort-ids). | +| `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`. | -#### Sort IDs - -| ID | Field | -| --- | ---------------- | -| 0 | Name | -| 1 | Email | -| 2 | Rank id | -| 3 | Last online | -| 4 | Join date | -| 5 | Amount of prints | - ### Response -| Parameter | Type | Description | -| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------- | -| `status` | boolean | True if the request was successful. | -| `message` | string | Error message if `status` is false. | -| `data` | array | An array of users. | -| `data[].id` | integer | The id of the user. | -| `data[].relation_id` | integer | The id of the user-company relation. | -| `data[].name` | string | The name of the user. | -| `data[].email_confirmed` | boolean | True if the user has confirmed their email address. | -| `data[].email` | string | The email address of the user. | -| `data[].phone` | string | The phone number of the user. | -| `data[].relation_created_at` | string | The date and time the user joined the company. | -| `data[].last_online` | string | The date and time the user was last online. Only present if user is approved | -| `data[].approved_at` | string | The date and time the user was approved. Only present if user is approved | -| `data[].org_account` | boolean | True if the user is an organization account. Only present if user is approved | -| `data[].total_prints` | integer | The total number of prints the user has made on this company. Only present if user is approved | -| `data[].rank` | integer | The id of the rank of the user. Only present if user is approved | -| `page_amount` | integer | The total number of pages. | +| 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. | ## Create Invitation Link @@ -114,7 +113,7 @@ curl https://api.simplyprint.io/{id}/users/CreateInvitationLink \ ```json { - "maxUses": 10 + "maxUses": 10 } ``` @@ -122,9 +121,9 @@ curl https://api.simplyprint.io/{id}/users/CreateInvitationLink \ ```json { - "status": true, - "message": null, - "link": "https://simplyprint.io/accept_invitation/b3d9b5a0-5b5b-11e9-8d7c-2d3b9e84aafd" + "status": true, + "message": null, + "link": "https://simplyprint.io/accept_invitation/b3d9b5a0-5b5b-11e9-8d7c-2d3b9e84aafd" } ``` @@ -133,8 +132,8 @@ curl https://api.simplyprint.io/{id}/users/CreateInvitationLink \ | Required permissions | -| -------------------- | -| `INVITE_USERS` | +|----------------------| +| `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. @@ -144,13 +143,13 @@ Please note that links with unlimited uses expire at the end of the day. `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. | @@ -168,12 +167,12 @@ curl https://api.simplyprint.io/{id}/users/InviteSpecificUser \ ```json { - "emails": [ - "test@example.com", - "test2@example.com" - ], - "rank": 192, - "lang": "en" + "emails": [ + "test@example.com", + "test2@example.com" + ], + "rank": 192, + "lang": "en" } ``` @@ -181,8 +180,8 @@ curl https://api.simplyprint.io/{id}/users/InviteSpecificUser \ ```json { - "status": true, - "message": null + "status": true, + "message": null } ``` @@ -191,8 +190,8 @@ curl https://api.simplyprint.io/{id}/users/InviteSpecificUser \ | Required permissions | -| -------------------- | -| `INVITE_USERS` | +|----------------------| +| `invite_users` | This endpoint invites one or more users to the company by email. @@ -201,14 +200,14 @@ This endpoint invites one or more users to the company by email. `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. | @@ -225,9 +224,9 @@ curl https://api.simplyprint.io/{id}/users/SetPendingUserState \ ```json { - "relation_id": 1234, - "approve": true, - "notify": true + "relation_id": 1234, + "approve": true, + "notify": true } ``` @@ -235,8 +234,8 @@ curl https://api.simplyprint.io/{id}/users/SetPendingUserState \ ```json { - "status": true, - "message": null + "status": true, + "message": null } ``` @@ -245,15 +244,15 @@ curl https://api.simplyprint.io/{id}/users/SetPendingUserState \ | Required permissions | -| -------------------- | -| `INVITE_USERS` | +|----------------------| +| `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. | @@ -261,7 +260,7 @@ curl https://api.simplyprint.io/{id}/users/SetPendingUserState \ ### Response | Parameter | Type | Description | -| --------- | ------- | ----------------------------------- | +|-----------|---------|-------------------------------------| | `status` | boolean | True if the request was successful. | | `message` | string | Error message if `status` is false. | @@ -278,8 +277,8 @@ curl https://api.simplyprint.io/{id}/users/ChangeUserRank \ ```json { - "relation_id": 1234, - "rank_id": 192 + "relation_id": 1234, + "rank_id": 192 } ``` @@ -287,8 +286,8 @@ curl https://api.simplyprint.io/{id}/users/ChangeUserRank \ ```json { - "status": true, - "message": null + "status": true, + "message": null } ``` @@ -297,14 +296,14 @@ curl https://api.simplyprint.io/{id}/users/ChangeUserRank \ `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. | @@ -321,7 +320,7 @@ curl https://api.simplyprint.io/{id}/users/DeleteUser \ ```json { - "user_id": 1234 + "user_id": 1234 } ``` @@ -329,8 +328,8 @@ curl https://api.simplyprint.io/{id}/users/DeleteUser \ ```json { - "status": true, - "message": null + "status": true, + "message": null } ``` @@ -339,8 +338,8 @@ curl https://api.simplyprint.io/{id}/users/DeleteUser \ | Required permissions | -| -------------------- | -| `DELETE_USER` | +|----------------------| +| `delete_user` | This endpoint deletes a user from the company. Use this endpoint with caution. @@ -349,12 +348,54 @@ This endpoint deletes a user from the company. Use this endpoint with caution. `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 + +```shell +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 + +```json +{ + "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. | diff --git a/source/includes/_webhooks.md b/source/includes/_webhooks.md new file mode 100644 index 00000000000..bd38aec6f89 --- /dev/null +++ b/source/includes/_webhooks.md @@ -0,0 +1,291 @@ +# 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 + +```shell +curl "https://api.simplyprint.io/{id}/webhooks/Get" \ + -H 'accept: application/json' \ + -H "X-API-KEY: {API_KEY}" +``` + +> Example response + +```json +{ + "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 + +```shell +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 + +```json +{ + "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](#webhook-event). | + +### 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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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. | + diff --git a/source/includes/gcode_macros.md b/source/includes/gcode_macros.md new file mode 100644 index 00000000000..d7cf81e0400 --- /dev/null +++ b/source/includes/gcode_macros.md @@ -0,0 +1,363 @@ +# GCode Macros + +## Get overview + +```shell +curl https://api.simplyprint.io/{id}/gcode_macros/GetOverview \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' +``` + +> Success response + +```json +{ + "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> AutoPrint (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 + +```shell +curl https://api.simplyprint.io/{id}/gcode_macros/GetSnippet?id=123 \ + -H 'accept: application/json' \ + -H 'X-API-KEY: {API_KEY}' \ +``` + +> Success Response + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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 + +```shell +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 + +```json +{ + "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`. | diff --git a/source/index.html.md b/source/index.html.md index 2a6d541312d..a5977e34fbf 100644 --- a/source/index.html.md +++ b/source/index.html.md @@ -11,14 +11,21 @@ toc_footers: includes: - printers - filament - - files + - jobs - api_files - queue + - printer_groups + - files - account - - jobs - users + - schools - slicer - tags + - custom_fields + - webhooks + - gcode_macros + - courses + - partner - permissions_scopes - errors