diff --git a/.gitignore b/.gitignore index 84a6718..0aa70ce 100644 --- a/.gitignore +++ b/.gitignore @@ -40,4 +40,5 @@ yarn.lock *.o *.so -NCRestAPI.code-workspace \ No newline at end of file +NCRestAPI.code-workspace +docs \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c99056..aad4619 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,33 @@ # Changelog -## 1.7.1 +## 1.8.1 + +### Fixed + +- `Get-NCScheduledTasks`: removed dead `-All`/`-PageNumber`/`-PageSize`/`-SortBy`/`-SortOrder` + parameters that always threw before being used. `-TaskId` is now mandatory. +- `New-NCOrgAccessGroup` / `New-NCDeviceAccessGroup`: optional `orgUnitIds`/`deviceIds`/`userIds` + arrays are no longer sent as `null` when omitted. +- `Get-NCStandardPsaCustomerMapping`: migrated from deprecated + `/api/standard-psa/customer-mapping/{id}` to `/api/standard-psa/customer/{id}/mappings`. +- `Get-NCFilters`, `New-NCServiceOrg`, `New-NCSite`: added `begin`/`process` blocks + for consistency and correct API instance lifecycle. + +### Changed + +- Standardized PascalCase variable references in body construction and + `ShouldProcess` calls across `New-NCCustomer`, `New-NCSite`, `New-NCServiceOrg`, + `Get-NCJobStatus`, `Get-NCDefaultDeviceProperty`. +- Fixed `.PARAMETER` casing in comment-based help to match parameter declarations + in `Get-NCDeviceServices`, `Get-NCApplianceTask`, `Get-NCScheduledTaskStatus`, + `New-NCSite`, `New-NCCustomer`, `New-NCScheduledTask`. +- Cleaned up indentation and removed extra blank lines in `Get-NCJobStatus`, + `Get-NCDefaultDeviceProperty`, `Get-NCDeviceAssets`, `Get-NCDeviceServices`. +- `SpecDrift.Tests.ps1` now reads root `spec.json` instead of + `Tests/fixtures/openapi-spec.json`. +- Added test asserting `Get-NCScheduledTasks` requires `-TaskId`. + +## 1.8.0 ### Fixed (surfaced by a full cmdlet matrix run against demo server) diff --git a/NCRestAPI.psd1 b/NCRestAPI.psd1 index 2b54c2a..592df45 100644 --- a/NCRestAPI.psd1 +++ b/NCRestAPI.psd1 @@ -9,7 +9,7 @@ RootModule = 'NCRestAPI.psm1' # Version number of this module. - ModuleVersion = '1.8.0' + ModuleVersion = '1.8.1' # Supported PSEditions CompatiblePSEditions = @('Desktop', 'Core') diff --git a/Public/Get-NCApplianceTask.ps1 b/Public/Get-NCApplianceTask.ps1 index 9c56e4d..61c869d 100644 --- a/Public/Get-NCApplianceTask.ps1 +++ b/Public/Get-NCApplianceTask.ps1 @@ -5,11 +5,11 @@ Retrieves the appliance-task information for a given task ID from the N-central .DESCRIPTION The `Get-NCApplianceTask` function retrieves the appliance-task information for a specified task ID from the N-central API. -.PARAMETER taskId +.PARAMETER TaskId Specifies the task ID for which to fetch the appliance-task information. This parameter is mandatory. .EXAMPLE -PS C:\> Get-NCApplianceTask -taskId "abc123" -Verbose +PS C:\> Get-NCApplianceTask -TaskId "abc123" -Verbose Retrieves the appliance-task information for the task with ID "abc123" and enables verbose output. .INPUTS diff --git a/Public/Get-NCDefaultDeviceProperty.ps1 b/Public/Get-NCDefaultDeviceProperty.ps1 index 5fd2475..4b9c931 100644 --- a/Public/Get-NCDefaultDeviceProperty.ps1 +++ b/Public/Get-NCDefaultDeviceProperty.ps1 @@ -43,16 +43,8 @@ function Get-NCDefaultDeviceProperty { begin { $api = Get-NCRestApiInstance } - - process { - Write-Verbose "[FUNCTION] Get-NCDefaultDeviceProperty: invoked." - $endpoint = "api/org-units/$orgUnitId/custom-properties/device-custom-property-defaults/$propertyId" - - Write-Verbose "[FUNCTION] Retrieving default device property with endpoint: $endpoint." - $response = $api.Get($endpoint) - return $response - - + Write-Verbose "[FUNCTION] Get-NCDefaultDeviceProperty: api/org-units/$OrgUnitId/custom-properties/device-custom-property-defaults/$PropertyId" + $api.Get("api/org-units/$OrgUnitId/custom-properties/device-custom-property-defaults/$PropertyId") } } diff --git a/Public/Get-NCDeviceAssets.ps1 b/Public/Get-NCDeviceAssets.ps1 index 818c9ee..8dac388 100644 --- a/Public/Get-NCDeviceAssets.ps1 +++ b/Public/Get-NCDeviceAssets.ps1 @@ -36,16 +36,8 @@ function Get-NCDeviceAssets { begin { $api = Get-NCRestApiInstance } - - process { - Write-Verbose "[FUNCTION] Get-NCDeviceAssets: invoked." - $endpoint = "api/devices/$DeviceId/assets" - - Write-Verbose "[FUNCTION] Retrieving device assets with endpoint: $endpoint." - $data = $api.Get($endpoint) - return $data - - + Write-Verbose "[FUNCTION] Get-NCDeviceAssets: api/devices/$DeviceId/assets" + $api.Get("api/devices/$DeviceId/assets") } } diff --git a/Public/Get-NCDeviceServices.ps1 b/Public/Get-NCDeviceServices.ps1 index cdd71de..8a37209 100644 --- a/Public/Get-NCDeviceServices.ps1 +++ b/Public/Get-NCDeviceServices.ps1 @@ -6,11 +6,11 @@ Retrieves service monitor status for a device from the N-central API. The `Get-NCDeviceServices` function retrieves the service monitor status for a device from the N-central API. It requires a device ID to specify the device whose service monitor status is to be retrieved. -.PARAMETER deviceId +.PARAMETER DeviceId The device ID for which to retrieve service monitor status. This parameter is mandatory. .EXAMPLE -PS C:\> Get-NCDeviceServices -deviceId 12345 -Verbose +PS C:\> Get-NCDeviceServices -DeviceId 12345 -Verbose Retrieves the service monitor status for the device with the ID 12345 with verbose output enabled. .INPUTS @@ -36,16 +36,8 @@ function Get-NCDeviceServices { begin { $api = Get-NCRestApiInstance } - - process { - Write-Verbose "[FUNCTION] Get-NCDeviceServices: invoked." - $endpoint = "api/devices/$DeviceId/service-monitor-status" - - Write-Verbose "[FUNCTION] Retrieving device services for endpoint: $endpoint." - $data = $api.Get($endpoint) - return $data - - + Write-Verbose "[FUNCTION] Get-NCDeviceServices: api/devices/$DeviceId/service-monitor-status" + $api.Get("api/devices/$DeviceId/service-monitor-status") } } diff --git a/Public/Get-NCFilters.ps1 b/Public/Get-NCFilters.ps1 index fe6dec8..4b375c1 100644 --- a/Public/Get-NCFilters.ps1 +++ b/Public/Get-NCFilters.ps1 @@ -33,23 +33,24 @@ function Get-NCFilters { [string]$SortOrder = 'asc' ) - $api = Get-NCRestApiInstance - $endpoint = 'api/device-filters' + begin { $api = Get-NCRestApiInstance } - $queryParameters = @{} - if ($ViewScope -and $ViewScope -ne 'ALL') { $queryParameters['viewScope'] = $ViewScope } - Add-NCCommonQuery -Parameters $queryParameters -Select $Select -SortBy $SortBy -SortOrder $SortOrder + process { + $endpoint = 'api/device-filters' - if ($All) { - return Invoke-NCPagedRequest -Endpoint $endpoint -QueryParameters $queryParameters - } - - if ($PageNumber) { $queryParameters['pageNumber'] = $PageNumber } + $queryParameters = @{} + if ($ViewScope -and $ViewScope -ne 'ALL') { $queryParameters['viewScope'] = $ViewScope } + Add-NCCommonQuery -Parameters $queryParameters -Select $Select -SortBy $SortBy -SortOrder $SortOrder + if ($All) { + return Invoke-NCPagedRequest -Endpoint $endpoint -QueryParameters $queryParameters + } - if ($PageSize) { $queryParameters['pageSize'] = $PageSize } else { $queryParameters['pageSize'] = 500 } + if ($PageNumber) { $queryParameters['pageNumber'] = $PageNumber } + if ($PageSize) { $queryParameters['pageSize'] = $PageSize } else { $queryParameters['pageSize'] = 500 } - $endpoint += ConvertTo-NCQueryString -Parameters $queryParameters - Write-Verbose "[FUNCTION] Get-NCFilters: $endpoint" - $api.Get($endpoint) + $endpoint += ConvertTo-NCQueryString -Parameters $queryParameters + Write-Verbose "[FUNCTION] Get-NCFilters: $endpoint" + $api.Get($endpoint) + } } diff --git a/Public/Get-NCJobStatus.ps1 b/Public/Get-NCJobStatus.ps1 index 76ed659..f50d903 100644 --- a/Public/Get-NCJobStatus.ps1 +++ b/Public/Get-NCJobStatus.ps1 @@ -36,16 +36,8 @@ function Get-NCJobStatus { begin { $api = Get-NCRestApiInstance } - - process { - Write-Verbose "[FUNCTION] Get-NCJobStatus: invoked." - $endpoint = "api/org-units/$orgUnitId/job-statuses" - - Write-Verbose "[FUNCTION] Retrieving job status with endpoint: $endpoint." - $data = $api.Get($endpoint) - return $data - - + Write-Verbose "[FUNCTION] Get-NCJobStatus: api/org-units/$OrgUnitId/job-statuses" + $api.Get("api/org-units/$OrgUnitId/job-statuses") } } diff --git a/Public/Get-NCScheduledTaskStatus.ps1 b/Public/Get-NCScheduledTaskStatus.ps1 index 5c91c22..b6a694a 100644 --- a/Public/Get-NCScheduledTaskStatus.ps1 +++ b/Public/Get-NCScheduledTaskStatus.ps1 @@ -5,26 +5,26 @@ Retrieves the status of a given task using the task ID or retrieves detailed sta .DESCRIPTION The `Get-NCScheduledTaskStatus` function retrieves the status of the given task from the N-central API based on the provided task ID. If the `-details` switch is specified, it retrieves detailed statuses for each device associated with the task instead. -.PARAMETER taskId +.PARAMETER TaskId Specifies the ID of the task for which status needs to be fetched. -.PARAMETER details +.PARAMETER Details If specified, retrieves detailed statuses per device for the given task. .EXAMPLE -PS C:\> Get-NCScheduledTaskStatus -taskId "12345" +PS C:\> Get-NCScheduledTaskStatus -TaskId "12345" Retrieves the aggregated status for the task with ID 12345. .EXAMPLE -PS C:\> Get-NCScheduledTaskStatus -taskId "12345" -details +PS C:\> Get-NCScheduledTaskStatus -TaskId "12345" -Details Retrieves the detailed status for the task with ID 12345. .EXAMPLE -PS C:\> Get-NCScheduledTaskStatus -taskId "12345" -Verbose +PS C:\> Get-NCScheduledTaskStatus -TaskId "12345" -Verbose Retrieves the aggregated status for the task with ID 12345 with verbose output enabled. .EXAMPLE -PS C:\> Get-NCScheduledTaskStatus -taskId "12345" -details -Verbose +PS C:\> Get-NCScheduledTaskStatus -TaskId "12345" -Details -Verbose Retrieves the detailed status for the task with ID 12345 with verbose output enabled. .INPUTS diff --git a/Public/Get-NCScheduledTasks.ps1 b/Public/Get-NCScheduledTasks.ps1 index b3262fb..d755bc1 100644 --- a/Public/Get-NCScheduledTasks.ps1 +++ b/Public/Get-NCScheduledTasks.ps1 @@ -1,55 +1,30 @@ <# .SYNOPSIS -Retrieves scheduled tasks from the N-central API. +Retrieves a scheduled task by ID from the N-central API. .DESCRIPTION -Returns all scheduled tasks, or a specific task by ID. Supports `-All` auto-pagination -and pipeline input. +N-central does not expose a bulk "list all scheduled tasks" endpoint. +Use Get-NCDeviceScheduledTasks to enumerate tasks per device. .PARAMETER TaskId Specific scheduled task to retrieve. -.PARAMETER All -Auto-paginate across all scheduled tasks. - .EXAMPLE Get-NCScheduledTasks -TaskId abc123 - -.EXAMPLE -Get-NCScheduledTasks -All #> function Get-NCScheduledTasks { - [CmdletBinding(DefaultParameterSetName = 'Page')] + [CmdletBinding()] [OutputType([pscustomobject])] param ( - [Parameter(ValueFromPipelineByPropertyName)] - [string]$TaskId, - - [Parameter(ParameterSetName = 'All')] - [switch]$All, - - [Parameter(ParameterSetName = 'Page')] - [int]$PageNumber, - - [Parameter(ParameterSetName = 'Page')] - [int]$PageSize, - - [string]$SortBy, - [ValidateSet('asc', 'desc')] - [string]$SortOrder = 'asc' + [Parameter(Mandatory, ValueFromPipelineByPropertyName)] + [ValidateNotNullOrEmpty()] + [string]$TaskId ) begin { $api = Get-NCRestApiInstance } process { - - Write-Verbose "[FUNCTION] Get-NCScheduledTasks: invoked." - if ($TaskId) { - return $api.Get("api/scheduled-tasks/$TaskId") - } - # N-central has no bulk "list all scheduled tasks" endpoint. /api/scheduled-tasks - # is a hypermedia navigation (returns only _links). Callers must fetch tasks per - # device via Get-NCDeviceScheduledTasks, or look up a known TaskId. - throw "Get-NCScheduledTasks requires -TaskId. N-central does not expose a bulk-list endpoint; use Get-NCDeviceScheduledTasks -DeviceId X to enumerate a device's tasks, or pipe devices in: Get-NCDevices -All | Get-NCDeviceScheduledTasks." + Write-Verbose "[FUNCTION] Get-NCScheduledTasks: api/scheduled-tasks/$TaskId" + $api.Get("api/scheduled-tasks/$TaskId") } } diff --git a/Public/Get-NCStandardPsaCustomerMapping.ps1 b/Public/Get-NCStandardPsaCustomerMapping.ps1 index 75b2757..4e780d1 100644 --- a/Public/Get-NCStandardPsaCustomerMapping.ps1 +++ b/Public/Get-NCStandardPsaCustomerMapping.ps1 @@ -3,7 +3,7 @@ Retrieves standard-PSA customer mappings for a given customer. .DESCRIPTION -GET /api/standard-psa/customer-mapping/{customerId}. +GET /api/standard-psa/customer/{customerId}/mappings. .EXAMPLE Get-NCStandardPsaCustomerMapping -CustomerId 100 @@ -18,7 +18,7 @@ function Get-NCStandardPsaCustomerMapping { ) begin { $api = Get-NCRestApiInstance } process { - Write-Verbose "[FUNCTION] Get-NCStandardPsaCustomerMapping: invoked." - $api.Get("api/standard-psa/customer-mapping/$CustomerId") + Write-Verbose "[FUNCTION] Get-NCStandardPsaCustomerMapping: api/standard-psa/customer/$CustomerId/mappings" + $api.Get("api/standard-psa/customer/$CustomerId/mappings") } } diff --git a/Public/New-NCCustomer.ps1 b/Public/New-NCCustomer.ps1 index 6134020..0a41ee1 100644 --- a/Public/New-NCCustomer.ps1 +++ b/Public/New-NCCustomer.ps1 @@ -7,62 +7,62 @@ The `New-NCCustomer` function creates a new customer in the N-central API. It requires several mandatory parameters to specify the service organization ID, customer name, and contact details. Optional parameters include license type, external ID, phone, and address details. -.PARAMETER soId +.PARAMETER SoId The service organization ID under which the customer will be created. This parameter is mandatory. -.PARAMETER customerName +.PARAMETER CustomerName The name of the customer. This parameter is mandatory. -.PARAMETER contactFirstName +.PARAMETER ContactFirstName The first name of the contact person for the customer. This parameter is mandatory. -.PARAMETER contactLastName +.PARAMETER ContactLastName The last name of the contact person for the customer. This parameter is mandatory. -.PARAMETER licenseType +.PARAMETER LicenseType The license type for the customer. -.PARAMETER externalId +.PARAMETER ExternalId An external ID for the customer. -.PARAMETER phone +.PARAMETER Phone The phone number for the customer. -.PARAMETER contactTitle +.PARAMETER ContactTitle The title of the contact person for the customer. -.PARAMETER contactEmail +.PARAMETER ContactEmail The email address of the contact person for the customer. -.PARAMETER contactPhone +.PARAMETER ContactPhone The phone number of the contact person for the customer. -.PARAMETER contactPhoneExt +.PARAMETER ContactPhoneExt The phone extension of the contact person for the customer. -.PARAMETER contactDepartment +.PARAMETER ContactDepartment The department of the contact person for the customer. -.PARAMETER street1 +.PARAMETER Street1 The primary street address of the customer. -.PARAMETER street2 +.PARAMETER Street2 The secondary street address of the customer. -.PARAMETER city +.PARAMETER City The city of the customer. -.PARAMETER stateProv +.PARAMETER StateProv The state or province of the customer. -.PARAMETER country +.PARAMETER Country The country of the customer. -.PARAMETER postalCode +.PARAMETER PostalCode The postal code of the customer. .EXAMPLE -PS C:\> New-NCCustomer -soId 123 -customerName "Acme Corp" -contactFirstName "John" -contactLastName "Doe" -Verbose +PS C:\> New-NCCustomer -SoId 123 -CustomerName "Acme Corp" -ContactFirstName "John" -ContactLastName "Doe" -Verbose Creates a new customer named "Acme Corp" under the service organization ID 123 with contact details for John Doe, with verbose output enabled. .INPUTS @@ -111,30 +111,29 @@ function New-NCCustomer { begin { $api = Get-NCRestApiInstance } process { - Write-Verbose "[FUNCTION] New-NCCustomer: invoked." $body = [ordered]@{ - customerName = $customerName - contactFirstName = $contactFirstName - contactLastName = $contactLastName + customerName = $CustomerName + contactFirstName = $ContactFirstName + contactLastName = $ContactLastName } - if ($licenseType) { $body.licenseType = $licenseType } - if ($externalId) { $body.externalId = $externalId } - if ($phone) { $body.phone = $phone } - if ($contactTitle) { $body.contactTitle = $contactTitle } - if ($contactEmail) { $body.contactEmail = $contactEmail } - if ($contactPhone) { $body.contactPhone = $contactPhone } - if ($contactPhoneExt) { $body.contactPhoneExt = $contactPhoneExt } - if ($contactDepartment) { $body.contactDepartment = $contactDepartment } - if ($street1) { $body.street1 = $street1 } - if ($street2) { $body.street2 = $street2 } - if ($city) { $body.city = $city } - if ($stateProv) { $body.stateProv = $stateProv } - if ($country) { $body.country = $country } - if ($postalCode) { $body.postalCode = $postalCode } - - if (-not $PSCmdlet.ShouldProcess($customerName, 'Create customer')) { return } - $api.Post("api/service-orgs/$soId/customers", $body) + if ($LicenseType) { $body.licenseType = $LicenseType } + if ($ExternalId) { $body.externalId = $ExternalId } + if ($Phone) { $body.phone = $Phone } + if ($ContactTitle) { $body.contactTitle = $ContactTitle } + if ($ContactEmail) { $body.contactEmail = $ContactEmail } + if ($ContactPhone) { $body.contactPhone = $ContactPhone } + if ($ContactPhoneExt) { $body.contactPhoneExt = $ContactPhoneExt } + if ($ContactDepartment) { $body.contactDepartment = $ContactDepartment } + if ($Street1) { $body.street1 = $Street1 } + if ($Street2) { $body.street2 = $Street2 } + if ($City) { $body.city = $City } + if ($StateProv) { $body.stateProv = $StateProv } + if ($Country) { $body.country = $Country } + if ($PostalCode) { $body.postalCode = $PostalCode } + + if (-not $PSCmdlet.ShouldProcess($CustomerName, 'Create customer')) { return } + $api.Post("api/service-orgs/$SoId/customers", $body) } } \ No newline at end of file diff --git a/Public/New-NCDeviceAccessGroup.ps1 b/Public/New-NCDeviceAccessGroup.ps1 index 6b49298..88cf1d6 100644 --- a/Public/New-NCDeviceAccessGroup.ps1 +++ b/Public/New-NCDeviceAccessGroup.ps1 @@ -68,9 +68,9 @@ function New-NCDeviceAccessGroup { $body = [ordered]@{ groupName = $GroupName groupDescription = $GroupDescription - deviceIds = $DeviceIds - userIds = $UserIds } +if ($null -ne $DeviceIds) { $body.deviceIds = $DeviceIds } +if ($null -ne $UserIds) { $body.userIds = $UserIds } $endpoint = "api/org-units/$OrgUnitId/device-access-groups" diff --git a/Public/New-NCOrgAccessGroup.ps1 b/Public/New-NCOrgAccessGroup.ps1 index 8eba0f1..e9f024c 100644 --- a/Public/New-NCOrgAccessGroup.ps1 +++ b/Public/New-NCOrgAccessGroup.ps1 @@ -73,10 +73,10 @@ function New-NCOrgAccessGroup { $body = [ordered]@{ groupName = $GroupName groupDescription = $GroupDescription - orgUnitIds = $OrgUnitIds - userIds = $UserIds autoIncludeNewOrgUnits = [bool]$AutoIncludeNewOrgUnits } +if ($null -ne $OrgUnitIds) { $body.orgUnitIds = $OrgUnitIds } +if ($null -ne $UserIds) { $body.userIds = $UserIds } $endpoint = "api/org-units/$OrgUnitId/access-groups" diff --git a/Public/New-NCScheduledTask.ps1 b/Public/New-NCScheduledTask.ps1 index 3c6cf71..77e26bd 100644 --- a/Public/New-NCScheduledTask.ps1 +++ b/Public/New-NCScheduledTask.ps1 @@ -5,19 +5,19 @@ Creates a direct-support scheduled task against a specific device in the N-centr .DESCRIPTION The `New-NCScheduledTask` function creates a direct-support scheduled task against a specific device. The task will be executed immediately against the device specified in the request payload. -.PARAMETER name +.PARAMETER Name Specifies the name of the task. This value must be unique. -.PARAMETER itemId +.PARAMETER ItemId Specifies the ID of the remote execution item. -.PARAMETER taskType +.PARAMETER TaskType Specifies the type of the task. Supported values are: AutomationPolicy, Script, or MacScript. -.PARAMETER customerId +.PARAMETER CustomerId Specifies the ID of the customer. -.PARAMETER deviceId +.PARAMETER DeviceId Specifies the ID of the device. .PARAMETER CredentialType diff --git a/Public/New-NCServiceOrg.ps1 b/Public/New-NCServiceOrg.ps1 index cd293da..9a0e7b1 100644 --- a/Public/New-NCServiceOrg.ps1 +++ b/Public/New-NCServiceOrg.ps1 @@ -113,34 +113,31 @@ function New-NCServiceOrg { [string]$PostalCode ) - $api = Get-NCRestApiInstance - - Write-Verbose "[FUNCTION] New-NCServiceOrg: invoked." - $body = [ordered]@{ - soName = $SoName - contactFirstName = $ContactFirstName - contactLastName = $ContactLastName + begin { $api = Get-NCRestApiInstance } + + process { + Write-Verbose "[FUNCTION] New-NCServiceOrg: invoked." + $body = [ordered]@{ + soName = $SoName + contactFirstName = $ContactFirstName + contactLastName = $ContactLastName + } + + if ($ExternalId) { $body.externalId = $ExternalId } + if ($Phone) { $body.phone = $Phone } + if ($ContactTitle) { $body.contactTitle = $ContactTitle } + if ($ContactEmail) { $body.contactEmail = $ContactEmail } + if ($ContactPhone) { $body.contactPhone = $ContactPhone } + if ($ContactPhoneExt) { $body.contactPhoneExt = $ContactPhoneExt } + if ($ContactDepartment) { $body.contactDepartment = $ContactDepartment } + if ($Street1) { $body.street1 = $Street1 } + if ($Street2) { $body.street2 = $Street2 } + if ($City) { $body.city = $City } + if ($StateProv) { $body.stateProv = $StateProv } + if ($Country) { $body.country = $Country } + if ($PostalCode) { $body.postalCode = $PostalCode } + + if (-not $PSCmdlet.ShouldProcess($SoName, 'Create service organization')) { return } + $api.Post('api/service-orgs', $body) } - - if ($ExternalId) { $body["externalId"] = $ExternalId } - if ($Phone) { $body["phone"] = $Phone } - if ($ContactTitle) { $body["contactTitle"] = $ContactTitle } - if ($ContactEmail) { $body["contactEmail"] = $ContactEmail } - if ($ContactPhone) { $body["contactPhone"] = $ContactPhone } - if ($ContactPhoneExt) { $body["contactPhoneExt"] = $ContactPhoneExt } - if ($ContactDepartment) { $body["contactDepartment"] = $ContactDepartment } - if ($Street1) { $body["street1"] = $Street1 } - if ($Street2) { $body["street2"] = $Street2 } - if ($City) { $body["city"] = $City } - if ($StateProv) { $body["stateProv"] = $StateProv } - if ($Country) { $body["country"] = $Country } - if ($PostalCode) { $body["postalCode"] = $PostalCode } - - $endpoint = "api/service-orgs" - - Write-Verbose "[FUNCTION] Creating new service organization with endpoint: $endpoint." - if (-not $PSCmdlet.ShouldProcess($soName, 'Create service organization')) { return } - - $response = $api.Post($endpoint, $body) - return $response } \ No newline at end of file diff --git a/Public/New-NCSite.ps1 b/Public/New-NCSite.ps1 index 3288bdf..4b0c268 100644 --- a/Public/New-NCSite.ps1 +++ b/Public/New-NCSite.ps1 @@ -7,62 +7,62 @@ The `New-NCSite` function creates a new site for a customer in the N-central API It requires several mandatory parameters to specify the customer ID, site name, and contact details. Optional parameters include license type, external ID, phone, and address details. -.PARAMETER customerId +.PARAMETER CustomerId The customer ID under which the site will be created. This parameter is mandatory. -.PARAMETER siteName +.PARAMETER SiteName The name of the site. This parameter is mandatory. -.PARAMETER contactFirstName +.PARAMETER ContactFirstName The first name of the contact person for the site. This parameter is mandatory. -.PARAMETER contactLastName +.PARAMETER ContactLastName The last name of the contact person for the site. This parameter is mandatory. -.PARAMETER licenseType +.PARAMETER LicenseType The license type for the site. -.PARAMETER externalId +.PARAMETER ExternalId An external ID for the site. -.PARAMETER phone +.PARAMETER Phone The phone number for the site. -.PARAMETER contactTitle +.PARAMETER ContactTitle The title of the contact person for the site. -.PARAMETER contactEmail +.PARAMETER ContactEmail The email address of the contact person for the site. -.PARAMETER contactPhone +.PARAMETER ContactPhone The phone number of the contact person for the site. -.PARAMETER contactPhoneExt +.PARAMETER ContactPhoneExt The phone extension of the contact person for the site. -.PARAMETER contactDepartment +.PARAMETER ContactDepartment The department of the contact person for the site. -.PARAMETER street1 +.PARAMETER Street1 The primary street address of the site. -.PARAMETER street2 +.PARAMETER Street2 The secondary street address of the site. -.PARAMETER city +.PARAMETER City The city of the site. -.PARAMETER stateProv +.PARAMETER StateProv The state or province of the site. -.PARAMETER country +.PARAMETER Country The country of the site. -.PARAMETER postalCode +.PARAMETER PostalCode The postal code of the site. .EXAMPLE -PS C:\> New-NCSite -customerId 123 -siteName "Main Office" -contactFirstName "John" -contactLastName "Doe" -Verbose +PS C:\> New-NCSite -CustomerId 123 -SiteName "Main Office" -ContactFirstName "John" -ContactLastName "Doe" -Verbose Creates a new site named "Main Office" under the customer ID 123 with contact details for John Doe, with verbose output enabled. .INPUTS @@ -108,35 +108,32 @@ function New-NCSite { [string]$PostalCode ) - $api = Get-NCRestApiInstance - - Write-Verbose "[FUNCTION] New-NCSite: invoked." - $body = [ordered]@{ - siteName = $siteName - contactFirstName = $contactFirstName - contactLastName = $contactLastName + begin { $api = Get-NCRestApiInstance } + + process { + Write-Verbose "[FUNCTION] New-NCSite: invoked." + $body = [ordered]@{ + siteName = $SiteName + contactFirstName = $ContactFirstName + contactLastName = $ContactLastName + } + + if ($LicenseType) { $body.licenseType = $LicenseType } + if ($ExternalId) { $body.externalId = $ExternalId } + if ($Phone) { $body.phone = $Phone } + if ($ContactTitle) { $body.contactTitle = $ContactTitle } + if ($ContactEmail) { $body.contactEmail = $ContactEmail } + if ($ContactPhone) { $body.contactPhone = $ContactPhone } + if ($ContactPhoneExt) { $body.contactPhoneExt = $ContactPhoneExt } + if ($ContactDepartment) { $body.contactDepartment = $ContactDepartment } + if ($Street1) { $body.street1 = $Street1 } + if ($Street2) { $body.street2 = $Street2 } + if ($City) { $body.city = $City } + if ($StateProv) { $body.stateProv = $StateProv } + if ($Country) { $body.country = $Country } + if ($PostalCode) { $body.postalCode = $PostalCode } + + if (-not $PSCmdlet.ShouldProcess($SiteName, 'Create site')) { return } + $api.Post("api/customers/$CustomerId/sites", $body) } - - if ($licenseType) { $body["licenseType"] = $licenseType } - if ($externalId) { $body["externalId"] = $externalId } - if ($phone) { $body["phone"] = $phone } - if ($contactTitle) { $body["contactTitle"] = $contactTitle } - if ($contactEmail) { $body["contactEmail"] = $contactEmail } - if ($contactPhone) { $body["contactPhone"] = $contactPhone } - if ($contactPhoneExt) { $body["contactPhoneExt"] = $contactPhoneExt } - if ($contactDepartment) { $body["contactDepartment"] = $contactDepartment } - if ($street1) { $body["street1"] = $street1 } - if ($street2) { $body["street2"] = $street2 } - if ($city) { $body["city"] = $city } - if ($stateProv) { $body["stateProv"] = $stateProv } - if ($country) { $body["country"] = $country } - if ($postalCode) { $body["postalCode"] = $postalCode } - - $endpoint = "api/customers/$customerId/sites" - - Write-Verbose "[FUNCTION] Creating new site with endpoint: $endpoint." - if (-not $PSCmdlet.ShouldProcess($siteName, 'Create site')) { return } - - $response = $api.Post($endpoint, $body) - return $response } \ No newline at end of file diff --git a/Tests/NCRestAPI.Tests.ps1 b/Tests/NCRestAPI.Tests.ps1 index 7fe0e9f..1de38fe 100644 --- a/Tests/NCRestAPI.Tests.ps1 +++ b/Tests/NCRestAPI.Tests.ps1 @@ -315,3 +315,11 @@ Describe 'Remove-NCDevice ShouldProcess' { $script:NCRestApiInstance.Deleted[0] | Should -Be 'api/devices/xyz?removeAgents=true' } } + +Describe 'Get-NCScheduledTasks parameter enforcement' { + It 'requires -TaskId (no bulk endpoint)' { + $cmd = Get-Command Get-NCScheduledTasks + $paramAttr = $cmd.Parameters['TaskId'].Attributes | Where-Object { $_ -is [System.Management.Automation.ParameterAttribute] } | Select-Object -First 1 + $paramAttr.Mandatory | Should -BeTrue + } +} diff --git a/Tests/SpecDrift.Tests.ps1 b/Tests/SpecDrift.Tests.ps1 index 66b4175..2223c6d 100644 --- a/Tests/SpecDrift.Tests.ps1 +++ b/Tests/SpecDrift.Tests.ps1 @@ -1,9 +1,8 @@ #Requires -Module @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' } <# -Asserts that every endpoint the module calls still exists in the bundled OpenAPI spec -at Tests/fixtures/openapi-spec.json. If N-central drops or renames an endpoint, the -fixture refresh job will fail and this test will then flag which wrapper is stale. +Asserts that every endpoint the module calls still exists in the bundled OpenAPI spec. +Prefers the root spec.json as the source of truth; falls back to the fixture spec when spec.json is absent. The intent is to catch drift, not to enforce coverage: it is fine for the spec to have endpoints the module doesn't wrap yet. @@ -13,7 +12,10 @@ endpoints the module doesn't wrap yet. # the full spec path list, then compare. $ModuleRoot = Split-Path -Parent $PSScriptRoot -$specPath = Join-Path $PSScriptRoot 'fixtures/openapi-spec.json' +$specPath = Join-Path $ModuleRoot 'spec.json' +if (-not (Test-Path $specPath)) { + $specPath = Join-Path $PSScriptRoot 'fixtures/openapi-spec.json' +} $spec = Get-Content $specPath -Raw | ConvertFrom-Json $specPaths = @($spec.paths.PSObject.Properties.Name) $specNormalized = $specPaths | ForEach-Object { ($_ -replace '\{[^}]+\}', '{id}') } | Sort-Object -Unique diff --git a/spec.json b/spec.json new file mode 100644 index 0000000..7a8a772 --- /dev/null +++ b/spec.json @@ -0,0 +1,18233 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "N-central API-Service", + "description": "

API Access

\n

In order to use the API-Service endpoints, ensure the following prerequisites are met:

\n
    \n
  1. User is created in N-central with appropriate permissions and configuration\n (roles, access groups, MFA disabled, 2FA disabled).
    2. \n
  2. API access is set up in N-central by having a JWT\n (Json Web Token, referred to as \"N-central User-API Token\") generated,\n acting as the permanent secret solely used for fetching access and refresh tokens.
    3. \n
\n

To access the API-Service endpoints, the JWT must first be exchanged with access and refresh tokens:

\n\n

API Pagination & Sorting

\n

Certain API-Service query endpoints support pagination and sorting through the use of query parameters.

\n

Pagination query parameters:

\n\n

A paginated response contains several related fields, such as pageSize, pageNumber, itemCount, totalItems,\n totalPages, _links (first, last, previous and next pages) and _warning (containing any warning messages,\n if present).

\n

Sorting query parameters:

\n\n

API Rate Limiting

\n

The API-Service endpoints are rate limited to ensure the stability, availability and performance of\n the overall system.

\n

Upon reaching such a rate limit, the endpoints return HTTP Status 429 - Too Many Requests.

\n

The system will accept further requests once existing in-flight requests are completed.

\n", + "version": "1.0" + }, + "servers": [ + { + "url": "/", + "description": "Default Server URL" + } + ], + "tags": [ + { + "name": "Maintenance Windows", + "description": "Maintenance Window CRUD operations" + }, + { + "name": "PSA", + "description": "PSA operations" + }, + { + "name": "Users", + "description": "User operations" + }, + { + "name": "Access Groups", + "description": "Access Group operations" + }, + { + "name": "Software Installers", + "description": "Agent and Probe Software Installers Management APIs." + }, + { + "name": "Job Statuses", + "description": "Job Status operations" + }, + { + "name": "Devices", + "description": "Device operations" + }, + { + "name": "Custom Properties", + "description": "Custom-Properties operations. These include both those associated with organization units and devices." + }, + { + "name": "Active Issues", + "description": "Active Issue operations" + }, + { + "name": "Device Filters", + "description": "Device filter operations" + }, + { + "name": "User Roles", + "description": "User role operations." + }, + { + "name": "Scheduled Tasks", + "description": "Scheduled tasks operations" + }, + { + "name": "Authentication", + "description": "Authentication operations used to obtain, refresh and validate API-Access tokens" + }, + { + "name": "Registration Tokens", + "description": "Registration-token operations. These include getting the token for customers and sites." + }, + { + "name": "Patch Reports", + "description": "Endpoints for generating and retrieving patch reports." + }, + { + "name": "API-Service", + "description": "Informative API operations" + }, + { + "name": "Organization Units", + "description": "Organization-Unit operations. These include customers, sites and service organizations." + }, + { + "name": "Device Tasks", + "description": "Operations related to retrieving and managing tasks for a device" + }, + { + "name": "Remote Control Tasks", + "description": "Remote control task operations" + } + ], + "paths": { + "/api/standard-psa/customer/{customerId}/mappings": { + "get": { + "tags": [ + "PSA" + ], + "summary": "Get Customer Mappings for a given customer ID.", + "description": "Retrieves customer mappings associated with the specified customer ID from the PSA system.", + "operationId": "getCustomerMappings", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer for whom to retrieve mappings.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd]NOT FOUND: ResourceNotFoundException: Customer with ID 12345 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing or invalid required information [customerId].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: Invalid customerId format: 'abc'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of customer mappings.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCustomerMapping" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "put": { + "tags": [ + "PSA" + ], + "summary": "Update Customer Mappings for a given customer ID.", + "description": "

\nUpdates customer mappings associated with the specified customer ID\nin the PSA system based on the provided mapping details.\n

\n\n

\nIf psaCompanyId is left empty for an existing mapping,\nthis will result in unmapping.\n

\n\n

\nIf psaSiteId is left empty for an existing mapping,\nthis will result in site unassignment,\nbut the company and contact mapping will be retained.\n

\n\n

\nIf psaContactId is left empty for an existing mapping,\nthis will result in contact unassignment,\nbut the company and site mappings will be retained.\n

\n", + "operationId": "updatePsaCustomerMappings", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer for whom to update mappings.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "requestBody": { + "description": "List of customer mapping update items containing the details for updating customer mappings.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCustomerMappingUpdateItem" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd]NOT FOUND: ResourceNotFoundException: Customer with ID 12345 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing or invalid required information [customerId, mapping details].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: Invalid customerId format: 'abc'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful update of customer mappings.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCustomerMapping" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/org-custom-property-defaults": { + "put": { + "tags": [ + "Custom Properties" + ], + "summary": "Update the default organization unit custom property.", + "description": "Update the default organization unit custom property for the given organization unit id and property id.", + "operationId": "modifyDefaultOrganizationUnitProperty", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The organization unit id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "requestBody": { + "description": "The request body for default custom property (DEVICE/ORGANIZATION_UNIT).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DefaultCustomPropertyModifyRequest" + }, + "example": { + "propagate": false, + "propertyId": 186156786, + "propertyName": "Prop Name 1", + "orgUnitId": 209, + "propagationType": "SITE_ONLY", + "defaultValue": "http://www.example.com", + "selectedOrgUnitIds": [ + 209, + 210 + ] + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Custom Property not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid organization unit id or property id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "The default organization unit custom property has been updated." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/custom-properties/{propertyId}": { + "get": { + "tags": [ + "Custom Properties" + ], + "summary": "Get the organization unit custom property.", + "description": "Get the organization unit custom property for the given organization unit id and property id.", + "operationId": "getOrganizationUnitProperty", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The organization unit id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "propertyId", + "in": "path", + "description": "The property id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Custom Property not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid organization unit id or property id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The organization unit custom property.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationCustomProperty" + }, + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "put": { + "tags": [ + "Custom Properties" + ], + "summary": "Update the organization unit custom property.", + "description": "Update the organization unit custom property for the given organization unit id and property id.", + "operationId": "modifyOrganizationUnitPropertyValue", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The organization unit id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "propertyId", + "in": "path", + "description": "The property id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "requestBody": { + "description": "The request body for custom property.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrgUnitCustomPropertyModification" + }, + "example": { + "value": "ORG_01-0620 VALUE" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Custom Property not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid organization unit id or property id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "The organization unit custom property has been updated.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPropertyUpdated" + } + } + } + }, + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationPropertyUpdated" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/notes/{noteId}": { + "put": { + "tags": [ + "Devices" + ], + "summary": "Modify a note on a device", + "description": "Modifies an existing note on the specified device.", + "operationId": "modifyNote", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "noteId", + "in": "path", + "description": "ID of the note to modify", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The new note content", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ModifyNoteRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device or note not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or user does not have permission to modify notes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request - Invalid input format", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Note modified successfully", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ModifyNoteResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "delete": { + "tags": [ + "Devices" + ], + "summary": "Delete a note from a device", + "description": "Deletes a note from the specified device. Returns 204 No Content on successful deletion. This operation is idempotent: deleting a non-existent noteId still returns 204 No Content.", + "operationId": "deleteNote", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "noteId", + "in": "path", + "description": "ID of the note to delete", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or user does not have permission to delete notes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request - Invalid input format", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Note deleted successfully, or note did not exist (idempotent)" + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/custom-properties/{propertyId}": { + "get": { + "tags": [ + "Custom Properties" + ], + "summary": "Get the device custom property.", + "description": "Get the device custom property for the given device id and property id.", + "operationId": "getDeviceCustomProperty", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "The device id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "propertyId", + "in": "path", + "description": "The property id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Custom Property not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid device id or property id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the device custom property.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrganizationCustomProperty" + }, + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "put": { + "tags": [ + "Custom Properties" + ], + "summary": "Modify Device Custom Property", + "description": "Modifies one custom property for a device.", + "operationId": "modifyDeviceProperty", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "Device ID to update property for.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "propertyId", + "in": "path", + "description": "Custom property ID that is associated with the device.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The request body for device custom property.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeviceCustomPropertyModification" + }, + "example": { + "value": "ORG_01-0620 VALUE" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device or Device Custom Property Not Found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid input", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Request was successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DevicePropertyUpdated" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/assets/lifecycle-info": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieve a device asset lifecycle information by Device ID.", + "description": "Retrieves a device asset lifecycle information with a specific id.", + "operationId": "getDeviceWarrantyInfo", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of device information.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/AssetLifecycleDetails" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "put": { + "tags": [ + "Devices" + ], + "summary": "Modifies the Asset Lifecycle Information by Device Id.", + "description": "Modifies the Asset Lifecycle Information for a device with a specific id.Please note that updateWarrantyError is read only.", + "operationId": "putAssetLifecycleInfo", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be modified.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssetLifecyclePutRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Successful modification of device lifecycle information." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "patch": { + "tags": [ + "Devices" + ], + "summary": "Modifies the Asset Lifecycle Information by Device Id.", + "description": "Modifies the Asset Lifecycle Information for a device with a specific id.Please note that updateWarrantyError is read only.", + "operationId": "patchAssetLifecycleInfo", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be modified.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AssetLifecyclePatchRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Successful modification of device lifecycle information." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/maintenance-windows": { + "put": { + "tags": [ + "Maintenance Windows" + ], + "summary": "Modifies existing device patch maintenance windows by it's given ScheduleId.", + "description": "Modifies patch maintenance windows by given Schedule Id. Currently only supports Patch maintenance windows. And only windows created at the device level can be modified.", + "operationId": "modifyMaintenanceWindows", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MaintenanceWindowsPutRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Maintenance Window not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Successfully modified window/s. ", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/MaintenanceWindowResponse" + } + } + } + } + }, + "security": [ + { + "API-Access Token": [] + } + ] + }, + "post": { + "tags": [ + "Maintenance Windows" + ], + "summary": "Adds set of maintenance windows for a list of given devices.", + "description": "Adds set of maintenance windows for a given device.The provided list of maintenance windows, will be applied to every device in the list.", + "operationId": "addMaintenanceWindowsByDeviceIds", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MaintenanceWindowsRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Successfully added maintenance window/s.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MaintenanceWindowResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "delete": { + "tags": [ + "Maintenance Windows" + ], + "summary": "Deletes device patch maintenance windows by given list of Schedule Ids.", + "description": "Deletes patch maintenance windows by given list of Schedule Ids. Currently only supports Patch maintenance windows. And only windows created at the device level can be deleted.", + "operationId": "deleteMaintenanceWindowsByScheduleIds", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/MaintenanceWindowsDeleteRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Schedule Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successfully deleted window/s. ", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/MaintenanceWindowResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/standard-psa/{psaType}/credential": { + "post": { + "tags": [ + "PSA" + ], + "summary": "Validate Standard PSA Credentials.", + "description": "Validates the credentials for the standard PSA system and returns a response indicating the validity. The only supported standard PSA integration to use with this endpoint is 3 (Tigerpaw).", + "operationId": "validatePsaCredentials", + "parameters": [ + { + "name": "psaType", + "in": "path", + "description": "The type of the PSA system for which credentials are being validated.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCredentialRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd]NOT FOUND: ResourceNotFoundException: Psa with type 5.0 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing required information[psaType, psaUsername, psaPassword].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: PSA username must not be empty." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful validation of the PSA credentials.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StandardPsaCredentialsValidateGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/service-orgs": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a list of all service organizations.", + "description": "Returns a list of all service organizations.", + "operationId": "listServiceOrganizations", + "parameters": [ + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of ervice organizations.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseServiceOrganization" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Organization Units" + ], + "summary": "Creates a new service organization (SO).", + "description": "Creates a new service organization with the specified details.", + "operationId": "createServiceOrganization", + "requestBody": { + "description": "The information for the service organization (SO) to be created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceOrganizationCreation" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Org Unit not found: '555'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid resource format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: SO Create -- Service Organization name is required and cannot be blank: SO Name: '%s'" + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Request was successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServiceOrganizationCreated" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/service-orgs/{soId}/customers": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a list of all customers under a service organization.", + "description": "Returns a list of all customers under a service organization.", + "operationId": "listCustomers", + "parameters": [ + { + "name": "soId", + "in": "path", + "description": "The ID of the a service organization.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of customers.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseCustomer" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Organization Units" + ], + "summary": "Creates a customer.", + "description": "Creates a new customer with the specified details.", + "operationId": "createCustomer", + "parameters": [ + { + "name": "soId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The information for the customer to be created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerCreation" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Org Unit not found: '555'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid resource format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: Customer Create -- Name is required and cannot be blank: Name: '%s'" + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Request was successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomerCreated" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/server-info/extra/authenticated": { + "post": { + "tags": [ + "API-Service" + ], + "summary": "Get extra information about the version of different systems in N-central using credentials.", + "description": "Get extra information about the version of different systems in N-central using credentials.", + "operationId": "apiExtraAuthenticated", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/VersionInfoAuthenticatedRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not found.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid input format.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The versions of the systems when authenticated.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/VersionInfoResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/scheduled-tasks/direct": { + "post": { + "tags": [ + "Scheduled Tasks" + ], + "summary": "Create a direct-support schedule task.", + "description": "Create a direct-support schedule task against a specific device.\nAs a direct-support schedule task, the task will be executed immediately against a single device.\nFor more information about the request payload,\nplease review below the schema of the relevant data type:\n DirectSupportTask,\n ScheduledTaskCredential, and\n ScheduledTaskParameter.\n", + "operationId": "createRemoteExecutionTaskDirect", + "requestBody": { + "description": "The task to be created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DirectSupportTask" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Successful creation of direct support task.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduledTaskCreateResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/report/patch-comparison": { + "post": { + "tags": [ + "Patch Reports" + ], + "summary": "Submits a request to generate a patch comparison report.", + "description": "Submits a request to generate a patch comparison report.", + "operationId": "generatePatchComparisonReport", + "requestBody": { + "description": "The request body containing the report generation parameters.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PatchComparisonReportRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Resource Not Found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceNotFoundException" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DmsLoginException" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessDeniedException" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiServiceRuntimeException" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Patch Report Generation request submitted successfully.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/PatchComparisonReportResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/users": { + "get": { + "tags": [ + "Users" + ], + "summary": "Retrieve the list of users.", + "description": "Retrieves the list of users within a specified org unit.", + "operationId": "listUsers", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the org unit for which to retrieve the users.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The size of each page. Use -1 for unlimited size, which retrieves all users.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string", + "enum": [ + "lastName", + "name", + "username", + "description", + "accountstatus", + "enabled", + "isenabled", + "locked", + "isLocked", + "currentssoprovider", + "ssoproviders", + "ldap", + "isldap", + "accessgroups", + "roles", + "twofactorenabled", + "apionlyuser", + "soname", + "customername", + "sitename" + ] + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The sort order, defaulting to ASC if unspecified.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "desc", + "descending" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of user list.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponseUser" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Users" + ], + "summary": "Create a new user in the specified org unit.", + "description": "Creates a new user within the specified organization unit. Requires USERS_EDIT permission.", + "operationId": "createUser", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the org unit in which to create the user.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The user creation request body.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Invalid or expired authentication token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid input data.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Insufficient permissions (USERS_EDIT required).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "User created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserCreateResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/user-roles": { + "get": { + "tags": [ + "User Roles" + ], + "summary": "PREVIEW: Retrieve a list of user roles for a given organization unit.", + "description": "Returns a list of user roles for a given organization unit.

NOTE:This endpoint is currently in a preview stage.", + "operationId": "listUserRoles", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which user roles information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the result will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of user roles.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/QueryResponseUserRole" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "User Roles" + ], + "summary": "PREVIEW: Add a new user role for a given organization unit.", + "description": "Add a new user role for a organization unit and return the role id.

NOTE:This endpoint is currently in a preview stage.", + "operationId": "addUserRole", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which new role needs to be added.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateUserRoleRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Successful creation of user role.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/CreateUserRoleResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/device-access-groups": { + "post": { + "tags": [ + "Access Groups" + ], + "summary": "Creates a new device type access group.", + "description": "Creates a new device type access group with the specified details.", + "operationId": "createDeviceAccessGroup", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeviceAccessGroupCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Org Unit not found: '555'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid resource format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: InvalidAccessGroupCreateRequestException: Invalid orgUnitId format: 'test'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Request was successful." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/access-groups": { + "get": { + "tags": [ + "Access Groups" + ], + "summary": "Retrieve Access Groups Information for an Org Unit by ID.", + "description": "Retrieves access group information for an organization unit with a specific id.", + "operationId": "listAccessGroups", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which access groups information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the result will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Org Unit not found: '999'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: InvalidInputFormatException: Invalid orgUnitId format: someString." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of access groups information. If access group id is a negative number, the response will be empty.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/QueryResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Access Groups" + ], + "summary": "Creates a new organization unit type access group.", + "description": "Creates a new organization unit type access group with the specified details.", + "operationId": "createOrgUnitAccessGroup", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OrgUnitTypeAccessGroupCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Org Unit not found: '555'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid resource format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: InvalidAccessGroupCreateRequestException: Invalid orgUnitId format: 'test'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Request was successful." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/services/actions": { + "post": { + "tags": [ + "Devices" + ], + "summary": "Perform an action on Windows Services.", + "description": "Sends a control action (Start, Stop, Restart, Pause, or Resume) to one or more Windows Services running on the specified managed device via the N-central reactive agent.", + "operationId": "performWindowsServiceAction", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "Numeric ID of the target device.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WindowsServiceActionRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or insufficient permissions for the target device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid request body (missing or blank service names, unknown action, or non-numeric deviceId).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Unexpected DMS error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Action dispatched successfully. The response reflects the state reported by the device agent.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/WindowsServiceActionResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/remote-control-task": { + "post": { + "tags": [ + "Remote Control Tasks" + ], + "summary": "Create a remote-control task.", + "description": "Creates a new remote-control task in N-central for a specified device.\nAllocates a RemoteControlTaskID, resolves the effective RemoteControlType,\nbrokers with the underlying RC adapter (e.g. MSP Anywhere / NTR / RDP),\nand returns the BrowserURI the caller must launch to start the session,\nalong with an initial TaskStatus.\n", + "operationId": "createRemoteControlTask", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "requestBody": { + "description": "The remote-control task to be created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteControlTaskRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found — deviceId does not exist or is not visible to the caller.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure — token is missing, expired, or invalid.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request — remoteControlType is invalid or request body validation failed.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden — caller's role does not grant remote-control access to the device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error — unexpected error from DMS or RC broker.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict — device is not remote-controllable, or the resolved remoteControlType has no adapter configured.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Remote-control task created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RemoteControlTaskCreatedResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/notes": { + "get": { + "tags": [ + "Devices" + ], + "summary": "List notes for a device", + "description": "Returns a paginated list of notes for the specified device, ordered by insertion time (newest first).", + "operationId": "listNotes", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device to list notes for", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to use the maximum configured page size.", + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Device not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or user does not have permission to view notes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request - Invalid parameters", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden - No permission to view device", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Notes retrieved successfully", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/QueryResponseDeviceNoteItem" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Devices" + ], + "summary": "Add a note to a device", + "description": "Adds a new note to the specified device. The note will be associated with the user specified in the request.", + "operationId": "addNote", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device to add the note to", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The note details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddNoteRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or user does not have permission to add notes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request - Invalid input", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Note added successfully", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/AddNoteResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "delete": { + "tags": [ + "Devices" + ], + "summary": "Delete multiple notes from a device", + "description": "Deletes multiple notes from the specified device in a single operation. Returns 204 No Content on successful deletion. This operation is idempotent: deleting non-existent noteIds still returns 204 No Content.", + "operationId": "deleteNoteBatch", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The note IDs to delete", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteBatchNoteRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Device not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or user does not have permission to delete notes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request - Invalid input format", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Notes deleted successfully, or notes did not exist (idempotent)" + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/notes": { + "post": { + "tags": [ + "Devices" + ], + "summary": "Add a note to multiple devices", + "description": "Adds the same note to multiple devices in a single operation. The note will be associated with the user specified in the request.", + "operationId": "addNoteBatch", + "requestBody": { + "description": "The batch note details", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AddBatchNoteRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "One or more devices not found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure or user does not have permission to add notes", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request - Invalid input", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Notes added successfully to all devices", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/AddBatchNoteResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/device": { + "post": { + "tags": [ + "Devices" + ], + "summary": "Add a new device.", + "description": "Adds a new device to N-central.", + "operationId": "addDevice", + "requestBody": { + "description": "The request body containing the device information to add.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeviceAddRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Device added successfully.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/DeviceAddResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/customers/{customerId}/software/installers": { + "get": { + "tags": [ + "Software Installers" + ], + "summary": "Get Software Installers", + "description": "Retrieves a list of software installers for a specific customer.", + "operationId": "getSoftwareDownloadPage", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer.", + "required": true, + "schema": { + "pattern": "^[1-9]\\d*$", + "type": "string" + } + }, + { + "name": "softwareType", + "in": "query", + "description": "Type of software to filter by. Supported values are: Agent, Probe, Other, All.\nIf not provided, defaults to All.\n", + "example": "Agent" + }, + { + "name": "installerType", + "in": "query", + "description": "Type of installer to filter by. Supported values are: Generic, Custom, All.\nIf not provided, defaults to All.\n", + "example": "Generic" + } + ], + "responses": { + "404": { + "description": "Resource not found." + }, + "401": { + "description": "Unauthorized access - invalid or missing credentials." + }, + "400": { + "description": "Invalid request parameters." + }, + "403": { + "description": "Forbidden - insufficient permissions to access the resource." + }, + "500": { + "description": "Internal server error." + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of software installers.", + "content": { + "*/*": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/InstallerSoftware" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Software Installers" + ], + "summary": "Generate Software Download Link", + "description": "Generates a software download link for a specific customer.", + "operationId": "generateSoftwareDownloadLink", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer.", + "required": true, + "schema": { + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GenerateSoftwareDownloadRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Resource not found." + }, + "401": { + "description": "Unauthorized access - invalid or missing credentials." + }, + "400": { + "description": "Invalid request parameters." + }, + "403": { + "description": "Forbidden - insufficient permissions to access the resource." + }, + "500": { + "description": "Internal server error." + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful generation of software download link.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/GenerateSoftwareDownloadLinkResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/customers/{customerId}/sites": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "PREVIEW: Retrieve a list of sites under a customer.", + "description": "Returns a list of all sites under a customer.


NOTE:This endpoint is currently in a preview stage.", + "operationId": "listSites_1", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the a customer.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Customer of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of sites.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseSite" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "Organization Units" + ], + "summary": "PREVIEW: Creates a site.", + "description": "Creates a new site with the specified details.

NOTE:This endpoint is currently in a preview stage.", + "operationId": "createSite", + "parameters": [ + { + "name": "customerId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "The information for the customer to be created.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCreation" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Org Unit not found: '555'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid resource format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: Site Create -- Name is required and cannot be blank: Name: '%s'" + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "201": { + "description": "Request was successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SiteCreated" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/custom-psa/tickets": { + "get": { + "tags": [ + "PSA" + ], + "summary": "List the custom psa tickets related links.", + "description": "List the custom psa tickets related links.", + "operationId": "customPsaTicketsRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "custom-psa-ticket-info": "/api/custom-psa/tickets/{customPsaTicketId}" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "PSA" + ], + "summary": "Create a Custom PSA Ticket in N-central.", + "description": "Creates a Custom PSA Ticket in N-central based on the provided information. The endpoint is exclusive for CUSTOM PSA Integrations, NOT for ConnectWise, AutoTask, TigerPaw or other managed PSAs.The token used must be associated with Custom PSA Integration user and can be generated from the N-central UI under PSA Integration Setup page. ", + "operationId": "createCustomTicket", + "requestBody": { + "description": "The request body containing the necessary information for creating the Custom PSA Ticket.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketCreateRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid request format or missing required fields.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: InvalidInputFormatException: Missing required field 'title'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Custom PSA Ticket created successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketCreateResponse" + } + } + } + }, + "201": { + "description": "Created", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketCreateResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/custom-psa/tickets/{customPsaTicketId}": { + "get": { + "tags": [ + "PSA" + ], + "summary": "Retrieve detailed information for a specific Custom PSA Ticket by ID without PSA credentials.", + "description": "Retrieves detailed information for a specific Custom PSA Ticket without requiring PSA credentials. The endpoint is exclusive to CUSTOM PSA Integrations, NOT for ConnectWise, AutoTask, TigerPaw or other managed PSAs. This method assumes that the DMS token contains the necessary information for authentication. The token used must be associated with Custom PSA Integration user and can be generated from the N-central UI under PSA Integration Setup page. ", + "operationId": "getCustomTicketInfoWithoutPsaCreds", + "parameters": [ + { + "name": "customPsaTicketId", + "in": "path", + "description": "The unique identifier of the Custom PSA ticket to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid psaTicketId format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: InvalidInputFormatException: Invalid customPsaTicketId format: string." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the Custom PSA ticket information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "post": { + "tags": [ + "PSA" + ], + "summary": "Retrieve detailed information for a specific Custom PSA Ticket by ID.", + "description": "Retrieves detailed information for a specific Custom PSA Ticket. The endpoint is exclusive to CUSTOM PSA Integrations, NOT for ConnectWise, AutoTask, TigerPaw or other managed PSAs.", + "operationId": "getCustomTicketInfo", + "parameters": [ + { + "name": "customPsaTicketId", + "in": "path", + "description": "The unique identifier of the Custom PSA ticket to retrieve.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCredentialRequest" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid psaTicketId format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: InvalidInputFormatException: Invalid customPsaTicketId format: string." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the Custom PSA ticket information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/custom-psa/tickets/{customPsaTicketId}/resolve": { + "post": { + "tags": [ + "PSA" + ], + "summary": "Resolve a Custom PSA Ticket in N-central.", + "description": "Resolves a Custom PSA Ticket in N-central based on the provided ticket ID. The endpoint is exclusive for CUSTOM PSA Integrations, NOT for ConnectWise, AutoTask, TigerPaw or other managed PSAs.This method assumes that the DMS token contains the necessary information for authentication. The token used must be associated with Custom PSA Integration user and can be generated from the N-central UI under PSA Integration Setup page. ", + "operationId": "resolveCustomTicket", + "parameters": [ + { + "name": "customPsaTicketId", + "in": "path", + "description": "The unique identifier of the Custom PSA Ticket to resolve.", + "required": true, + "schema": { + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid customPsaTicketId format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: InvalidInputFormatException: Invalid customPsaTicketId format: string." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Custom PSA Ticket resolved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketResolveResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/custom-psa/tickets/{customPsaTicketId}/reopen": { + "post": { + "tags": [ + "PSA" + ], + "summary": "Reopen a Custom PSA Ticket in N-central.", + "description": "Reopens a Custom PSA Ticket in N-central based on the provided ticket ID. The endpoint is exclusive for CUSTOM PSA Integrations, NOT for ConnectWise, AutoTask, TigerPaw or other managed PSAs.This method assumes that the DMS token contains the necessary information for authentication. The token used must be associated with Custom PSA Integration user and can be generated from the N-central UI under PSA Integration Setup page. ", + "operationId": "reopenCustomTicket", + "parameters": [ + { + "name": "customPsaTicketId", + "in": "path", + "description": "The unique identifier of the Custom PSA Ticket to reopen.", + "required": true, + "schema": { + "pattern": "^[1-9]\\d*$", + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid customPsaTicketId format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: InvalidInputFormatException: Invalid customPsaTicketId format: string." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Custom PSA Ticket reopened successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CustomPsaTicketReopenResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/auth/sso": { + "post": { + "tags": [ + "Authentication" + ], + "summary": "Obtains access and refresh tokens using an SSO access token.", + "description": "

\nThis endpoint authenticates users via SSO (Single Sign-On) tokens obtained from an\nexternal identity provider (IdP). The SSO token is passed in the Authorization header\nand will be validated when subsequent API calls are made to N-central.\n

\n

\nNote: SSO tokens have their own expiry controlled by the identity provider.\nThe api-service tokens returned here are separate and have their own expiry.\n

\n", + "operationId": "authenticateSso", + "parameters": [ + { + "name": "X-ACCESS-EXPIRY-OVERRIDE", + "in": "header", + "description": "Override the access-expiry. Format: (time)(unit). For example: 120s for 120 seconds. The unit can be 's' for second, 'm' for minute and 'h' for hour. NOTE: The specified time cannot be longer than the system-wide setting (default to 1h).", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-REFRESH-EXPIRY-OVERRIDE", + "in": "header", + "description": "Override the refresh-expiry. Format: (time)(unit). For example: 120s for 120 seconds. The unit can be 's' for second, 'm' for minute and 'h' for hour. NOTE: The specified time cannot be longer than the system-wide setting (default to 25h).", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure - Invalid or expired SSO token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Authentication is successful.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/AuthenticateResponse" + } + } + } + } + }, + "security": [ + { + "SSO_Access_Token": [] + } + ] + } + }, + "/api/auth/refresh": { + "post": { + "tags": [ + "Authentication" + ], + "summary": "Obtains a new API-Access token using a valid refresh token.", + "description": "

\nIn order to refresh the API-Access token, you must first authenticate to obtain a valid \"refresh token\"\nand include it in the request body.\n

\n", + "operationId": "refresh", + "parameters": [ + { + "name": "X-ACCESS-EXPIRY-OVERRIDE", + "in": "header", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-REFRESH-EXPIRY-OVERRIDE", + "in": "header", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Refresh token.", + "content": { + "text/plain": { + "schema": { + "type": "string" + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Refreshed authentication.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/AuthRefreshResponse" + } + } + } + } + } + } + }, + "/api/auth/logout": { + "post": { + "tags": [ + "Authentication" + ], + "summary": "Invalidates the current session.", + "description": "

\nLogs out the user by invalidating the api-service session associated with the\nprovided access token. After this call, both the access token and its corresponding\nrefresh token will no longer be accepted.\n

\n

\nNote: For SSO users, this does not revoke the SSO token with the identity provider.\nThe client is responsible for handling SSO token revocation separately.\n

\n", + "operationId": "logout", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Invalid or expired access token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Logout successful." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/auth/authenticate": { + "post": { + "tags": [ + "Authentication" + ], + "summary": "Obtains access and refresh tokens using an N-central User-API Token (JWT).", + "description": "

\nThis method essentially uses the HTTP bearer authentication.\nTo obtain the \"N-central User-API Token (JWT)\", visit the N-central UI.\nThen navigate to Administration → User Management → Users → Click on user → API Access → GENERATE JSON WEB TOKEN.\n

\n", + "operationId": "authenticate", + "parameters": [ + { + "name": "X-ACCESS-EXPIRY-OVERRIDE", + "in": "header", + "description": "Override the access-expiry. Format: (time)(unit). For example: 120s for 120 seconds. The unit can be 's' for second, 'm' for minute and 'h' for hour. NOTE: The specified time cannot be longer than the system-wide setting (default to 1h).", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "X-REFRESH-EXPIRY-OVERRIDE", + "in": "header", + "description": "Override the refresh-expiry. Format: (time)(unit). For example: 120s for 120 seconds. The unit can be 's' for second, 'm' for minute and 'h' for hour. NOTE: The specified time cannot be longer than the system-wide setting (default to 25h).", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Authentication is successful.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/AuthenticateResponse" + } + } + } + } + }, + "security": [ + { + "N-central_User-API_Token_JWT": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/limits": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve customer limits.", + "description": "Returns the customer limits for the specified organization unit.", + "operationId": "getCustomerLimits", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the organization unit.", + "required": true, + "schema": { + "pattern": "^[1-9]\\d*$", + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of customer limits.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/GetCustomerLimitsResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "patch": { + "tags": [ + "Organization Units" + ], + "summary": "Update customer limits.", + "description": "Updates the customer limits for the specified organization unit.", + "operationId": "updateCustomerLimits", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the organization unit.", + "required": true, + "schema": { + "pattern": "^[1-9]\\d*$", + "type": "integer", + "format": "int32" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ModifyCustomerLimitRequest" + } + } + } + }, + "required": true + }, + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful update of customer limits.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ModifyCustomerLimitsResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api": { + "get": { + "tags": [ + "API-Service" + ], + "summary": "List links to other endpoints.", + "operationId": "apiRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "root": "/api", + "server-info": "/api/server-info", + "health": "/api/health", + "auth": "/api/auth", + "customers": "/api/customers", + "devices": "/api/devices", + "scheduled-tasks": "/api/scheduled-tasks" + } + } + } + } + } + } + } + }, + "/api/users": { + "get": { + "tags": [ + "Users" + ], + "summary": "List the user related links.", + "description": "User List.", + "operationId": "userRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "user-list - GET": "/api/org-units/{orgUnitId}/users" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/users/me": { + "get": { + "tags": [ + "Users" + ], + "summary": "Get the current authenticated user's information.", + "description": "Returns the user profile for whoever is making the request. Requires USERS_VIEW permission.", + "operationId": "getUserSelf", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Invalid or expired authentication token.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Insufficient permissions (USERS_VIEW required).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successfully retrieved the authenticated user's profile.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserSelfResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/standard-psa": { + "get": { + "tags": [ + "PSA" + ], + "summary": " List the standard psa related links.", + "description": "List the standard psa related links.", + "operationId": "standardPsaRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "standard-psa-validate-credential": "/api/standard-psa/{psaType}/credential" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/standard-psa/customers/{customerId}/companies": { + "get": { + "tags": [ + "PSA" + ], + "summary": "Get PSA Companies for a given customer ID.", + "description": "Retrieves the list of PSA companies associated with the specified customer ID from the PSA system.", + "operationId": "getPsaCompanies", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer for whom to retrieve PSA companies.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd]NOT FOUND: ResourceNotFoundException: Customer with ID 12345 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing or invalid required information [customerId].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: Invalid customerId format: 'abc'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of PSA companies.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCompany" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/standard-psa/customers/{customerId}/companies/{psaCompanyId}/sites": { + "get": { + "tags": [ + "PSA" + ], + "summary": "Get PSA Sites for a given customer ID and PSA company ID.", + "description": "Retrieves the list of PSA sites associated with the specified customer ID and PSA company ID from the PSA system.", + "operationId": "getPsaSites", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer for whom to retrieve PSA sites.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "psaCompanyId", + "in": "path", + "description": "The ID of the PSA company for which to retrieve sites.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Customer with ID 12345 or PSA Company with ID 67890 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing or invalid required information [customerId, psaCompanyId].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: Invalid customerId format: 'abc'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of PSA sites.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaSite" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/standard-psa/customers/{customerId}/companies/{psaCompanyId}/contacts": { + "get": { + "tags": [ + "PSA" + ], + "summary": "Get PSA Contacts for a given customer ID and PSA company ID.", + "description": "Retrieves the list of PSA contacts associated with the specified customer ID and PSA company ID from the PSA system.", + "operationId": "getPsaContacts", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer for whom to retrieve PSA contacts.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "psaCompanyId", + "in": "path", + "description": "The ID of the PSA company for which to retrieve contacts.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd]NOT FOUND: ResourceNotFoundException: Customer with ID 12345 or PSA Company with ID 67890 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing or invalid required information [customerId, psaCompanyId].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: Invalid customerId format: 'abc'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of PSA contacts.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaContact" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/standard-psa/customer-mapping/{customerId}": { + "get": { + "tags": [ + "PSA" + ], + "summary": "Get Customer Mappings for a given customer ID. [Deprecated]", + "description": "Retrieves customer mappings associated with the specified customer ID from the PSA system.", + "operationId": "getCustomerMappingsDeprecated", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the customer for whom to retrieve mappings.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd]NOT FOUND: ResourceNotFoundException: Customer with ID 12345 was not found!" + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Missing or invalid required information [customerId].", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "BAD REQUEST: BAD REQUEST: BadRequestException: Invalid customerId format: 'abc'." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of customer mappings.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PsaCustomerMapping" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/sites": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a list of all sites.", + "description": "Returns a list of all sites.", + "operationId": "listSites", + "parameters": [ + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of sites.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseSite" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/sites/{siteId}": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a site.", + "description": "Returns a site.", + "operationId": "getSite", + "parameters": [ + { + "name": "siteId", + "in": "path", + "description": "The ID of the a site.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Site of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the site.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/Site" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/sites/{siteId}/registration-token": { + "get": { + "tags": [ + "Registration Tokens" + ], + "summary": "PREVIEW: Retrieve a site registration token.", + "description": "Returns a site registration token.

NOTE:This endpoint is currently in a preview stage.", + "operationId": "getSiteRegistrationToken", + "parameters": [ + { + "name": "siteId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Site of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the site registration token.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/RegistrationTokenGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/service-orgs/{soId}": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a service organization.", + "description": "Returns a service organization.", + "operationId": "getServiceOrganization", + "parameters": [ + { + "name": "soId", + "in": "path", + "description": "The ID of the a service organization.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Service Organization of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the service organization.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ServiceOrganization" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/server-info": { + "get": { + "tags": [ + "API-Service" + ], + "summary": "Return version information of the running API-Service.", + "operationId": "apiRoot_1", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthValidateResponse" + }, + "example": { + "version": "3.1.0", + "jvmVersion": "17.0.9", + "ncentral": null + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/server-info/time": { + "get": { + "tags": [ + "API-Service" + ], + "summary": "Returns the server time information.", + "operationId": "getServerTimeInfo", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ServerTimeInfo" + }, + "example": { + "serverTime": "2026-02-26T15:15:30-05:00", + "timezone": "America/New_York", + "utcOffset": "-05:00" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/server-info/extra": { + "get": { + "tags": [ + "API-Service" + ], + "summary": "Get information about the version of different systems in N-central.", + "description": "Get extra information about the version of different systems in N-central.", + "operationId": "apiExtra", + "responses": { + "404": { + "description": "Not found.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid input format.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The versions of the systems.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/VersionInfoResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/scheduled-tasks": { + "get": { + "tags": [ + "Scheduled Tasks" + ], + "summary": "List the task-related links.", + "operationId": "taskRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "direct-support-task": "/api/scheduled-tasks/direct" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/scheduled-tasks/{taskId}": { + "get": { + "tags": [ + "Scheduled Tasks" + ], + "summary": "Retrieves general information for a given task.", + "description": "Retrieves general information for a given task using the task ID.", + "operationId": "getTask", + "parameters": [ + { + "name": "taskId", + "in": "path", + "description": "ID of the task for which information is to be retrieved.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of information.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduledTaskInfoResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/scheduled-tasks/{taskId}/status": { + "get": { + "tags": [ + "Scheduled Tasks" + ], + "summary": "Retrieves aggregated status for a given task.", + "description": "Retrieves the aggregated status associated with a given task using the task ID.", + "operationId": "getTaskStatus", + "parameters": [ + { + "name": "taskId", + "in": "path", + "description": "ID of the task for which aggregated status needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of aggregated status.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ScheduledTaskAggregatedStatusResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/scheduled-tasks/{taskId}/status/details": { + "get": { + "tags": [ + "Scheduled Tasks" + ], + "summary": "Retrieves detailed status per device for a given task.", + "description": "Retrieve a list of detailed statuses for each device associated with the given task using the task ID.", + "operationId": "listTaskStatusDetails", + "parameters": [ + { + "name": "taskId", + "in": "path", + "description": "ID of the task for which detailed status needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of status details.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseDetailsResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/report/{reportId}": { + "get": { + "tags": [ + "Patch Reports" + ], + "summary": "Retrieves a report by id.", + "description": "Retrieves a report with a specific id.", + "operationId": "getPatchComparisonReport", + "parameters": [ + { + "name": "reportId", + "in": "path", + "description": "ID of the report for which information needs to be fetched.", + "required": true, + "schema": { + "pattern": "^-?\\d+$", + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Resource Not Found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceNotFoundException" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DmsLoginException" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessDeniedException" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiServiceRuntimeException" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Patch Report Generation request submitted successfully.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/PatchComparisonReportResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a list of all organization units.", + "description": "Returns a list of all organization units.", + "operationId": "listOrganizationUnits", + "parameters": [ + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of organization units.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseOrganizationUnit" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve an organization unit.", + "description": "Returns an organization unit.", + "operationId": "getOrganizationUnit", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the organization unit.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Organization Unit of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the organization unit.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/OrganizationUnit" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/user-roles/{userRoleId}": { + "get": { + "tags": [ + "User Roles" + ], + "summary": "PREVIEW: Retrieve a user role for a given organization unit and user role id.", + "description": "Returns a user role for a given organization unit and user role id.

NOTE:This endpoint is currently in a preview stage.", + "operationId": "getUserRole", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which role is retrieved. The organization unit id is used to determine if role is modifiable at this level or not.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "userRoleId", + "in": "path", + "description": "ID of the user role id for which user roles information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of user role.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/UserRoleDetailsResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/registration-token": { + "get": { + "tags": [ + "Registration Tokens" + ], + "summary": "Retrieve a organization unit registration token.", + "description": "Returns a organization unit registration token.", + "operationId": "getOrganizationUnitRegistrationToken", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the a organization unit.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Organization of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Getting registration token using this API is not allowed (only CUSTOMER and SITE are allowed).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the customer registration token.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/RegistrationTokenGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/org-custom-property-defaults/{propertyId}": { + "get": { + "tags": [ + "Custom Properties" + ], + "summary": "Get the organization unit custom property.", + "description": "Get the organization unit custom property for the given organization unit id and property id.", + "operationId": "getCustomProperty", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The organization unit id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "propertyId", + "in": "path", + "description": "The property id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Custom Property not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid organization unit id or property id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The organization unit custom property.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DefaultCustomProperty" + }, + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "orgUnitId": 11090, + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE", + "selectedOrgUnitIds": [ + 11089, + 11090 + ] + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/job-statuses": { + "get": { + "tags": [ + "Job Statuses" + ], + "summary": "Fetch job statuses", + "description": "Fetch a list of job statuses for the given organization unit.", + "operationId": "listJobStatuses", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Organization unit not found.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid input format.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The list of job statuses.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/devices": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieve the list of devices by org unit id.", + "description": "Retrieves the list of devices from N-central for the logged in user.", + "operationId": "listDevicesByOrgUnitId", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "filterId", + "in": "query", + "description": "The ID of the filter to apply for this device list. Leave empty or unset to retrieve the unfiltered list.", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Set to -1 to retrieve the maximum-size items (deployment settings)Use 50 if the maximum-size is set to -1.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of device list.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/QueryResponseDevice" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/custom-properties": { + "get": { + "tags": [ + "Custom Properties" + ], + "summary": "Get the list of organization custom properties.", + "description": "Get the list of organization unit custom properties for the given organization unit id.", + "operationId": "listCustomerProperties", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The organization unit id.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid organization unit id.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The list of organization unit custom properties.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ListResponseOrganizationCustomProperty" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/custom-properties/device-custom-property-defaults/{propertyId}": { + "get": { + "tags": [ + "Custom Properties" + ], + "summary": "Retrieve Device Default Custom Property information by organization unit id and property id", + "description": "Retrieves default custom properties information", + "operationId": "getDeviceDefaultCustomProperty", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which information needs to be fetched", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "propertyId", + "in": "path", + "description": "ID of the property for which information needs to be fetched", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Organization Unit or Property Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of property information", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/DeviceCustomPropertyResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/children": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a list of all organization units children.", + "description": "Returns a list of all organization units under the specific organization unit.", + "operationId": "listOrganizationUnitChildren", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "The ID of the parent organization unit.If specified, only the children of the specified organization unit are retrieved.Leave empty or unset to retrieve the unfiltered list.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of organization units.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseOrganizationUnit" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/org-units/{orgUnitId}/active-issues": { + "get": { + "tags": [ + "Active Issues" + ], + "summary": "Fetch active issues", + "description": "Fetch a list of active issues for the given organization unit.
NOTE:Only organization units that are customers or sites are currently supported.", + "operationId": "listActiveIssues", + "parameters": [ + { + "name": "orgUnitId", + "in": "path", + "description": "ID of the organization unit for which active issues needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Must be positive number.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the result will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid input format.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal server error.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "The list of active issues.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/QueryResponseActiveIssue" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/health": { + "get": { + "tags": [ + "API-Service" + ], + "summary": "Return the start and current time of the server. This indicates that the server is running.", + "operationId": "health", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/Health" + } + } + } + } + } + } + }, + "/api/devices": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieve the list of devices.", + "description": "Retrieves the list of devices from N-central for the logged in user.", + "operationId": "listDevices", + "parameters": [ + { + "name": "filterId", + "in": "query", + "description": "The ID of the filter to apply for this device list. Leave empty or unset to retrieve the unfiltered list.", + "required": false, + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "Set to -1 to retrieve the maximum-size items (deployment settings)Use 50 if the maximum-size is set to -1.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of device list.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/QueryResponseDevice" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieve a device by ID.", + "description": "Retrieves a device with a specific id.", + "operationId": "getDeviceById", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of device information.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/DeviceResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + }, + "delete": { + "tags": [ + "Devices" + ], + "summary": "Delete a device by ID.", + "description": "Deletes a device with a specific id from N-central.", + "operationId": "deleteDevice", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device to be deleted.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "removeAgents", + "in": "query", + "description": "Whether to remove agents associated with the device. Default is false.", + "required": false, + "schema": { + "type": "boolean", + "default": false + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResourceNotFoundException" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DmsLoginException" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessDeniedException" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiServiceRuntimeException" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "204": { + "description": "Device deleted successfully." + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/service-monitor-status": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieves the status of the service monitoring tasks for a given device.", + "description": "Retrieves the status of the service monitoring tasks for a given device.", + "operationId": "getDeviceStatus", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of monitoring task status information.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseDeviceServiceMonitoringStatus" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/scheduled-tasks": { + "get": { + "tags": [ + "Device Tasks" + ], + "summary": "Retrieve tasks for a specific device.", + "description": "Retrieves a list of tasks associated with a specified device using the device ID.", + "operationId": "listTasksForDevice", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which the tasks need to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of tasks.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseTaskStatusResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/remote-control-type": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieves the remote-control configuration for a device.", + "description": "Retrieves whether the device is remote-controllable and the resolved remote-control type and state.", + "operationId": "getRemoteControlType", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which remote-control configuration is requested.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "404": { + "description": "The device id is unknown to the server.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failure, or the authenticated user does not have permission to view the remote-control configuration for the requested device (DMS fault 3013).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Invalid deviceId format.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Caller's role does not grant access to the API (returned by upstream authorization filters).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the remote-control configuration.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/DeviceRemoteControlInfoResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/maintenance-windows": { + "get": { + "tags": [ + "Maintenance Windows" + ], + "summary": "Retrieves all maintenance windows for a device.", + "description": "Retrieves all maintenance windows for a given device.", + "operationId": "getMaintenanceWindowsByDeviceId", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of maintenance window information.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseMaintenanceWindowGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/custom-properties": { + "get": { + "tags": [ + "Custom Properties" + ], + "summary": "Retrieve Device Custom Properties by device id", + "description": "Retrieves custom properties list for a device.", + "operationId": "listDeviceCustomProperties", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which information needs to be fetched", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Not Found", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of list of device's custom properties", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseDeviceCustomProperty" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/assets": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieve Asset Information for a device by ID.", + "description": "Retrieves complete asset information for a device with a specific id.

Also See: DeviceAssetInfoResponse ", + "operationId": "getAssetInfo", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which asset information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of device asset information.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/DeviceAssetInfoResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/devices/{deviceId}/activation-key": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Generate an activation key for a device.", + "description": "Generates an activation key for a specific device.", + "operationId": "generateActivationKey", + "parameters": [ + { + "name": "deviceId", + "in": "path", + "description": "ID of the device for which the activation key needs to be generated.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Activation key generated successfully.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/DeviceActivationKeyResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/device-filters": { + "get": { + "tags": [ + "Device Filters" + ], + "summary": "Retrieve the list of filters.", + "description": "Retrieves the list of filters from N-central for the logged in user.", + "operationId": "listFilters", + "parameters": [ + { + "name": "viewScope", + "in": "query", + "description": "Scope of the filters. Defaults to 'ALL'.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "ALL", + "OWN_AND_USED" + ] + } + }, + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled).", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of filter list.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseFilter" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/customers": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a list of all customers.", + "description": "Returns a list of all customers.", + "operationId": "listCustomers_1", + "parameters": [ + { + "name": "pageNumber", + "in": "query", + "description": "The page number to retrieve. Starts at 1. If not provided, defaults to the first page. For SOAP clients migrating from the offset-based EI2 customerList: offset = (pageNumber - 1) * pageSize.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "pageSize", + "in": "query", + "description": "The number of items to retrieve per page. Set to -1 to retrieve all items without pagination (if enabled). For SOAP clients migrating from the offset-based EI2 customerList, pageSize maps to limit.", + "schema": { + "type": "integer", + "format": "int32" + } + }, + { + "name": "select", + "in": "query", + "description": "The select expression.", + "schema": { + "type": "string" + } + }, + { + "name": "sortBy", + "in": "query", + "description": "The name of a field to sort the result by.", + "schema": { + "type": "string" + } + }, + { + "name": "sortOrder", + "in": "query", + "description": "The order in which the order will follow -- case insensitive and default to ASC.", + "schema": { + "type": "string", + "default": "ASC", + "enum": [ + "asc", + "ascending", + "natural", + "desc", + "descending", + "reverse" + ] + } + } + ], + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of customers.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ListResponseCustomer" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/customers/{customerId}": { + "get": { + "tags": [ + "Organization Units" + ], + "summary": "Retrieve a customer.", + "description": "Returns a customer.", + "operationId": "getCustomer", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the a customer.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Customer of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the customer.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/Customer" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/customers/{customerId}/registration-token": { + "get": { + "tags": [ + "Registration Tokens" + ], + "summary": "PREVIEW: Retrieve a customer registration token.", + "description": "Returns a customer registration token.

NOTE:This endpoint is currently in a preview stage.", + "operationId": "getCustomerRegistrationToken", + "parameters": [ + { + "name": "customerId", + "in": "path", + "description": "The ID of the a customer.", + "required": true, + "schema": { + "type": "integer", + "format": "int32" + } + } + ], + "responses": { + "404": { + "description": "Customer of the ID is not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the customer registration token.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/RegistrationTokenGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/custom-psa": { + "get": { + "tags": [ + "PSA" + ], + "summary": "List the custom psa related links.", + "description": "List the custom psa related links.", + "operationId": "customPsaRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "custom-psa-ticket-info": "/api/custom-psa/tickets/{customPsaTicketId}", + "custom-psa-tickets": "/api/custom-psa/tickets" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/auth": { + "get": { + "tags": [ + "Authentication" + ], + "summary": "List the authentication-related links.", + "operationId": "authRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "authenticate": "/api/auth/authenticate", + "sso": "/api/auth/sso", + "refresh": "/api/auth/refresh", + "logout": "/api/auth/logout", + "validate": "/api/auth/validate" + } + } + } + } + } + } + }, + "/api/auth/validate": { + "get": { + "tags": [ + "Authentication" + ], + "summary": "Check the validity of the API-Access token.", + "description": "

\nIn order to validate the API-Access token, you must first authenticate to obtain the API-Access token.\n

\n", + "operationId": "validate", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Authentication is successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AuthValidateResponse" + }, + "example": { + "message": "The token is valid." + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/appliance-tasks/{taskId}": { + "get": { + "tags": [ + "Devices" + ], + "summary": "Retrieves the appliance-task information.", + "description": "Retrieves the appliance-task information for a given taskId.", + "operationId": "getApplianceTaskInformationDetails", + "parameters": [ + { + "name": "taskId", + "in": "path", + "description": "ID of the appliance-task for which information needs to be fetched.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Device Id not found.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of appliance-task information.", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ApplianceTaskInformation" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/access-groups": { + "get": { + "tags": [ + "Access Groups" + ], + "summary": "List the access group related links.", + "description": "Lists all the API endpoints for access group related actions.", + "operationId": "accessGroupRoot", + "responses": { + "404": { + "description": "Not Found", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "401": { + "description": "Unauthorized", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LinksResponse" + }, + "example": { + "_links": { + "access-group-list - GET": "/api/org-units/{orgUnitId}/access-groups", + "access-group-info - GET": "/api/access-groups/{accessGroupId}", + "org-unit-access-group-create - POST": "/api/org-units/{orgUnitId}/access-groups", + "device-access-group-create - POST": "/api/org-units/{orgUnitId}/device-access-groups" + } + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + }, + "/api/access-groups/{accessGroupId}": { + "get": { + "tags": [ + "Access Groups" + ], + "summary": "Retrieve detailed information for a specific Access Group by ID.", + "description": "Retrieves detailed information for a specific Access Group, including its name, type, and ", + "operationId": "getAccessGroup", + "parameters": [ + { + "name": "accessGroupId", + "in": "path", + "description": "The unique identifier of the access group for which information is being requested.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "404": { + "description": "Not Found.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 404, + "message": "[ID=abcd] NOT FOUND: ResourceNotFoundException: Access group was not found. Id: '999'." + } + } + } + } + }, + "401": { + "description": "Authentication Failure.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 401, + "message": "[ID=abcd] UNAUTHORIZED: UnauthorizedException: Missing authorization header bearer." + } + } + } + } + }, + "400": { + "description": "Invalid Access Group Id format.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 400, + "message": "[ID=abcd] BAD REQUEST: InvalidInputFormatException: Invalid orgUnitId format: stringValue." + } + } + } + } + }, + "403": { + "description": "Forbidden", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "500": { + "description": "Internal Server Error.", + "content": { + "application/json": { + "schema": { + "type": "string", + "example": { + "status": 500, + "message": "[ID=abcd] INTERNAL SERVER ERROR: UnexpectedDmsResponseException: Unexpected response from DMS: The DMS response indicates a non-success status code : 500." + } + } + } + } + }, + "409": { + "description": "Conflict", + "content": { + "*/*": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + } + }, + "200": { + "description": "Successful retrieval of the access group information. If the access group is not found (or a negative number is provided), the response will be empty.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AccessGroupGetResponse" + } + } + } + } + }, + "security": [ + { + "API-Access_Token": [] + } + ] + } + } + }, + "components": { + "schemas": { + "ErrorResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ValidationError" + } + } + }, + "description": "Error response", + "example": { + "status": 400, + "message": "[ID=2b85998f-26a3-467a] Multiple Validations Failed.", + "errors": [ + { + "field": "installStatuses", + "message": "Invalid Install Status Values ['INVALID']" + }, + { + "field": "startDate", + "message": "startDate must be in the format YYYY-MM-DD" + } + ] + } + }, + "ValidationError": { + "type": "object", + "properties": { + "field": { + "type": "string" + }, + "message": { + "type": "string" + } + } + }, + "PsaCustomerMappingUpdateItem": { + "required": [ + "customerId" + ], + "type": "object", + "properties": { + "customerId": { + "minimum": 1, + "type": "integer", + "format": "int32" + }, + "psaCompanyId": { + "type": "integer", + "format": "int32" + }, + "psaSiteId": { + "type": "integer", + "format": "int32" + }, + "psaContactId": { + "type": "integer", + "format": "int32" + } + }, + "description": "PSA Customer Mapping Update Item", + "example": { + "customerId": 456, + "psaCompanyId": 101112, + "psaSiteId": 131415, + "psaContactId": 123 + } + }, + "PsaCustomerMapping": { + "type": "object", + "properties": { + "psaContactId": { + "type": "integer", + "format": "int32" + }, + "customerId": { + "type": "integer", + "format": "int32" + }, + "customerName": { + "type": "string" + }, + "psaLocationId": { + "type": "integer", + "format": "int32" + }, + "psaCompanyId": { + "type": "integer", + "format": "int32" + }, + "psaSiteId": { + "type": "integer", + "format": "int32" + }, + "contactId": { + "type": "integer", + "format": "int32", + "deprecated": true + }, + "locationId": { + "type": "integer", + "format": "int32", + "deprecated": true + }, + "psaCustomerId": { + "type": "integer", + "format": "int32", + "deprecated": true + }, + "siteId": { + "type": "integer", + "format": "int32", + "deprecated": true + } + }, + "description": "Customer Mapping details", + "example": { + "contactId": 123, + "customerId": 456, + "customerName": "Acme Corp", + "locationId": 789, + "psaCustomerId": 101112, + "siteId": 131415 + } + }, + "DefaultCustomPropertyModifyRequest": { + "type": "object", + "properties": { + "propagate": { + "type": "boolean", + "description": "A boolean flag to specify whether to propagate changes to children Organization Units." + }, + "propertyId": { + "type": "integer", + "description": "The property id.", + "format": "int32" + }, + "propertyName": { + "type": "string", + "description": "The property name." + }, + "propagationType": { + "type": "string", + "description": "The way how the property value changes are propagated down the organization unit hierarchy.", + "enum": [ + "NO_PROPAGATION", + "SERVICE_ORGANIZATION_ONLY", + "SERVICE_ORGANIZATION_AND_CUSTOMER_AND_SITE", + "SERVICE_ORGANIZATION_AND_CUSTOMER", + "SERVICE_ORGANIZATION_AND_SITE", + "CUSTOMER_AND_SITE", + "CUSTOMER_ONLY", + "SITE_ONLY", + "NO_PROPAGATION", + "SERVICE_ORGANIZATION_ONLY", + "SERVICE_AND_ORGANIZATION", + "SERVICE_AND_ORGANIZATION_AND_DEVICE", + "SERVICE_AND_DEVICE", + "ORGANIZATION_AND_DEVICE", + "ORGANIZATION_ONLY", + "DEVICE_ONLY" + ] + }, + "defaultValue": { + "type": "string", + "description": "The default value of the property." + }, + "selectedOrgUnitIds": { + "type": "array", + "description": "The entire list of organization unit IDs to which the custom property is applicable. The list includes the 'Home' organization unit and all its child organization units.", + "items": { + "type": "integer", + "description": "The entire list of organization unit IDs to which the custom property is applicable. The list includes the 'Home' organization unit and all its child organization units.", + "format": "int32" + } + }, + "enumeratedValueList": { + "type": "array", + "description": "The list of allowed values for the property, if the property type is ENUMERATED.", + "items": { + "type": "string", + "description": "The list of allowed values for the property, if the property type is ENUMERATED." + } + } + }, + "description": "The request body for default custom property (DEVICE/ORGANIZATION_UNIT).", + "example": { + "propagate": false, + "propertyId": 186156786, + "propertyName": "Prop Name 1", + "orgUnitId": 209, + "propagationType": "SITE_ONLY", + "defaultValue": "http://www.example.com", + "selectedOrgUnitIds": [ + 209, + 210 + ] + } + }, + "OrgUnitCustomPropertyModification": { + "type": "object", + "properties": { + "propertyId": { + "type": "string", + "description": "The property id.", + "readOnly": true + }, + "propertyName": { + "type": "string", + "description": "The property name.", + "readOnly": true + }, + "propertyType": { + "type": "string", + "description": "The property type.", + "readOnly": true, + "enum": [ + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD" + ] + }, + "value": { + "type": "string", + "description": "The property value." + }, + "enumeratedValueList": { + "type": "array", + "description": "The possible value of the property.", + "readOnly": true, + "items": { + "type": "string", + "description": "The possible value of the property.", + "readOnly": true + } + } + }, + "description": "The custom property (DEVICE/ORGANIZATION_UNIT).", + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE" + } + }, + "OrganizationPropertyUpdated": { + "type": "object", + "properties": { + "_warnings": { + "type": "array", + "description": "The list of warnings.", + "items": { + "type": "string", + "description": "The list of warnings." + } + } + }, + "description": "The organization property update result.", + "example": { + "_warnings": [ + "Property Type is ignored during update." + ] + } + }, + "ModifyNoteRequest": { + "required": [ + "note" + ], + "type": "object", + "properties": { + "note": { + "maxLength": 32000, + "minLength": 0, + "type": "string", + "description": "The new content of the note", + "example": "Updated note content" + } + }, + "description": "Request body for modifying an existing note on a device" + }, + "ModifyNoteResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "HTTP status code", + "format": "int32", + "example": 200 + }, + "message": { + "type": "string", + "description": "Status message indicating the result", + "example": "The note was modified successfully" + }, + "data": { + "$ref": "#/components/schemas/ModifyNoteResponseData" + } + }, + "description": "Response after successfully modifying a note on a device" + }, + "ModifyNoteResponseData": { + "type": "object", + "properties": { + "noteId": { + "type": "integer", + "description": "The ID of the note that was modified", + "format": "int32", + "example": 123 + }, + "deviceId": { + "type": "integer", + "description": "The ID of the device the note was modified on", + "format": "int32", + "example": 789 + } + }, + "description": "Data for the modified note" + }, + "DeviceCustomPropertyModification": { + "type": "object", + "properties": { + "propertyId": { + "type": "string", + "description": "The property id.", + "readOnly": true + }, + "propertyName": { + "type": "string", + "description": "The property name.", + "readOnly": true + }, + "propertyType": { + "type": "string", + "description": "The property type.", + "readOnly": true, + "enum": [ + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD" + ] + }, + "value": { + "type": "string", + "description": "The property value." + }, + "enumeratedValueList": { + "type": "array", + "description": "The possible value of the property.", + "readOnly": true, + "items": { + "type": "string", + "description": "The possible value of the property.", + "readOnly": true + } + } + }, + "description": "The custom property (DEVICE/ORGANIZATION_UNIT).", + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE" + } + }, + "DevicePropertyUpdated": { + "type": "object", + "properties": { + "_warnings": { + "type": "array", + "description": "The list of warnings.", + "items": { + "type": "string", + "description": "The list of warnings." + } + } + }, + "description": "The device property update result.", + "example": { + "_warnings": [ + "Property Type is ignored during update." + ] + } + }, + "AssetLifecyclePutRequest": { + "required": [ + "assetTag", + "cost", + "description", + "expectedReplacementDate", + "leaseExpiryDate", + "location", + "purchaseDate", + "warrantyExpiryDate" + ], + "type": "object", + "properties": { + "warrantyExpiryDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "leaseExpiryDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "expectedReplacementDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "purchaseDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "cost": { + "type": "number" + }, + "location": { + "type": "string" + }, + "assetTag": { + "type": "string" + }, + "description": { + "maxLength": 255, + "minLength": 0, + "type": "string" + }, + "updateWarrantyError": { + "type": "string", + "description": "This field is Read Only", + "readOnly": true + }, + "allNull": { + "type": "boolean" + } + }, + "description": "Asset Lifecycle details", + "example": { + "warrantyExpiryDate": "2022-12-31", + "leaseExpiryDate": "2022-12-31", + "expectedReplacementDate": "2022-12-31", + "purchaseDate": "2022-12-31", + "cost": 0.0, + "location": "location", + "assetTag": "assetTag", + "description": "description", + "updateWarrantyError": "updateWarrantyError" + } + }, + "Action": { + "type": "object", + "properties": { + "Key": { + "type": "string" + }, + "Value": { + "type": "string" + } + }, + "description": "Response for Maintenance Window Action.", + "example": " {\n \"key\": \"Install\",\n \"value\": \"871a0782-be12-a5c4-c57f-1bd6d9f7144e\",\n }\n" + }, + "ApplicableAction": { + "type": "object", + "properties": { + "type": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Action" + } + } + }, + "description": "Request/Response for Maintenance Window ApplicableAction.", + "example": " {\n \"type\": \"Patch\",\n \"actions\": [\n {\n \"key\": \"Install\",\n \"value\": \"871a0782-be12-a5c4-c57f-1bd6d9f7144e\",\n }\n ]\n }\n" + }, + "MaintenanceWindowRequest": { + "required": [ + "applicableAction", + "cron", + "duration", + "enabled", + "name", + "type" + ], + "type": "object", + "properties": { + "applicableAction": { + "type": "array", + "description": "Actions Applicable To Window", + "items": { + "$ref": "#/components/schemas/ApplicableAction" + } + }, + "cron": { + "type": "string", + "description": "Schedule represented as Cron" + }, + "duration": { + "type": "integer", + "description": "Maintenance Window should last for", + "format": "int32" + }, + "enabled": { + "type": "boolean", + "description": "Maintenance Window should last for" + }, + "name": { + "type": "string", + "description": "Name of Maintenance Window" + }, + "type": { + "type": "string", + "description": "Type of Maintenance Window (only allowed type is currently 'action')" + }, + "downtimeOnAction": { + "type": "boolean", + "description": "Place Device in Downtime During Reboot (Reboot Window)" + }, + "maxDowntime": { + "type": "integer", + "description": "Force Device out of Downtime After (Reboot Window) - used when 'downtimeOnAction' is true", + "format": "int32" + }, + "rebootMethod": { + "type": "string", + "description": "Reboot Method (Reboot Window), must be one of: ['allowUserToPostpone', 'forceUserToReboot', 'forceRebootWithoutNotification', 'onlyAcceptedReboot']" + }, + "rebootDelay": { + "type": "integer", + "description": "Minutes before continuing with reboot. (Reboot Window)", + "format": "int32" + }, + "userMessageEnabled": { + "type": "boolean", + "description": "Display Custom Message To User (Reboot Window)" + }, + "userMessage": { + "type": "string", + "description": "Custom message to display to user when 'userMessageEnabled' is true (Reboot Window)" + }, + "messageSenderEnabled": { + "type": "boolean", + "description": "Enable Custom Message Sender (Reboot Window)" + }, + "messageSender": { + "type": "string", + "description": "Message from when 'messageSenderEnabled' is true (Reboot Window)" + }, + "preserveStateEnabled": { + "type": "boolean", + "description": "Preserve State of Device During Reboot (/g flag) (Reboot Window)" + }, + "scheduleId": { + "type": "integer", + "description": "Maintenance Window ID, Required when using PUT, ignored otherwise", + "format": "int32" + } + }, + "description": "Represents a single maintenance Window.", + "example": { + "applicableAction": [ + { + "type": "Patch", + "actions": [ + { + "Key": "detect", + "Value": null + } + ] + } + ], + "name": "Test Maintenance Window", + "type": "action", + "cron": "0 0 0 ? 2 1,4 *", + "duration": 60, + "enabled": true, + "maxDowntime": 0, + "rebootMethod": "allowUserToPostpone", + "rebootDelay": 0, + "downtimeOnAction": false, + "userMessageEnabled": false, + "userMessage": null, + "messageSenderEnabled": false, + "messageSender": null, + "preserveStateEnabled": false + } + }, + "MaintenanceWindowsPutRequest": { + "type": "object", + "properties": { + "maintenanceWindows": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MaintenanceWindowRequest" + } + } + }, + "description": "Request for modifying a set of maintenance Windows to a list of devices.", + "example": { + "maintenanceWindows": [ + { + "scheduleId": 123456789, + "applicableAction": [ + { + "type": "Patch", + "actions": [ + { + "Key": "detect", + "Value": null + } + ] + } + ], + "name": "Test Maintenance Window", + "type": "action", + "cron": "0 0 0 ? 2 1,4 *", + "duration": 60, + "enabled": true, + "maxDowntime": 0, + "rebootMethod": "allowUserToPostpone", + "rebootDelay": 0, + "downtimeOnAction": false, + "userMessageEnabled": false, + "userMessage": null, + "messageSenderEnabled": false, + "messageSender": null, + "preserveStateEnabled": false + } + ] + } + }, + "MaintenanceWindowResponse": { + "type": "object", + "properties": { + "success": { + "type": "boolean" + } + }, + "description": "General Response for maintenance window action.", + "example": { + "success": true + } + }, + "Data": { + "type": "object", + "properties": { + "userId": { + "type": "integer", + "format": "int32" + } + } + }, + "StandardPsaCredentialsValidateGetResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Data" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Represents the response for validating PSA credentials.\nThe validation result is encapsulated under the \"_extra\" field.\n", + "example": { + "data": { + "isPsaCredentialsValid": true + }, + "_links": {} + } + }, + "PsaCredentialRequest": { + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "description": "Representation of PSA credentials.", + "example": { + "username": "username@domain.com", + "password": "myPassword!" + } + }, + "ServiceOrganizationCreation": { + "required": [ + "soName" + ], + "type": "object", + "properties": { + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "soName": { + "type": "string", + "description": "Name of the service organization." + } + }, + "description": "Data object for organization unit.", + "example": { + "soName": "New SO name", + "contactFirstName": "first name", + "contactLastName": "last name", + "externalId": "extId", + "phone": "phone", + "contactTitle": "contact title", + "contactEmail": "contact@email.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "postalCode": "A1A 1A1" + } + }, + "ServiceOrganizationCreated": { + "type": "object", + "properties": { + "soId": { + "type": "integer", + "description": "Id of the created service organization.", + "format": "int32" + } + }, + "description": "Represents the response of creating a new service organization and contains its ID.\n", + "example": { + "soId": 123 + } + }, + "CustomerCreation": { + "required": [ + "customerName" + ], + "type": "object", + "properties": { + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "customerName": { + "type": "string", + "description": "Name of the customer." + }, + "licenseType": { + "type": "string", + "description": "License type of the customer.", + "default": "Professional" + } + }, + "description": "Data object for customer.", + "example": { + "customerName": "New customer name", + "contactFirstName": "first name", + "contactLastName": "last name", + "licenseType": "Professional", + "externalId": "extId", + "phone": "phone", + "contactTitle": "contact title", + "contactEmail": "contact@email.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "postalCode": "A1A 1A1" + } + }, + "CustomerCreated": { + "type": "object", + "properties": { + "customerId": { + "type": "integer", + "description": "Id of the created customer.", + "format": "int32" + } + }, + "description": "Represents the response of creating a new customer and contains the newly created customer ID.\n", + "example": { + "customerId": 123 + } + }, + "VersionInfoResponse": { + "type": "object", + "properties": { + "data": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The data containing version info extra details." + }, + "description": "The data containing version info extra details." + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Represents the response for version info extra. It provides details about each system and its value\nsuch as and others.\n", + "example": { + "data": { + "_extra": { + "Installation: Deployment Product Version": "2024.1.0.11", + "Installation: UI Product Version": "2024.1.0.11", + "NVISION: Licensed": "true" + } + }, + "_links": {} + } + }, + "VersionInfoAuthenticatedRequest": { + "type": "object", + "properties": { + "username": { + "type": "string" + }, + "password": { + "type": "string" + } + }, + "description": "Representation of credentials.", + "example": { + "username": "my.username@n-able.com", + "password": "myPassword!" + } + }, + "DirectSupportTask": { + "required": [ + "credential", + "customerId", + "deviceId", + "itemId", + "name", + "taskType" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The name of the task. This value must be unique." + }, + "itemId": { + "type": "integer", + "description": "The ID of the remote execution item. The item ID can be found in the N-central UI (\"Configuration\" -> \"Scheduled Tasks\" -> \"Script/software Repository\") and it must have \"Enable API\" flag \"ON\" (see in the N-central UI).", + "format": "int32" + }, + "taskType": { + "type": "string", + "description": "The type of the task. Supported values: AutomationPolicy, Script or MacScript.", + "enum": [ + "AutomationPolicy", + "Script", + "MacScript" + ] + }, + "customerId": { + "type": "integer", + "description": "The ID of the customer. The customer ID can be obtained using the 'GET /api/customers' endpoint.", + "format": "int32" + }, + "deviceId": { + "type": "integer", + "description": "The ID of the device. The device ID can be obtained using the 'GET /api/devices' endpoint.", + "format": "int32" + }, + "credential": { + "$ref": "#/components/schemas/ScheduledTaskCredential" + }, + "parameters": { + "type": "array", + "description": "The credential setting for the task.\nFor more information about the fields of ScheduledTaskParameter,\n please review its schema below.\n", + "items": { + "$ref": "#/components/schemas/ScheduledTaskParameter" + } + } + }, + "description": "'Direct support' scheduled task.", + "example": { + "name": "Test Task", + "itemId": 1, + "taskType": "Script", + "customerId": 100, + "deviceId": 987654321, + "credential": { + "type": "LocalSystem", + "username": null, + "password": null + }, + "parameters": [ + { + "name": "CommandLine", + "value": "killprocess.vbs /process:33022" + } + ] + } + }, + "ScheduledTaskCredential": { + "required": [ + "type" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "The credential type. Supported values: LocalSystem, DeviceCredentials and CustomCredentials.", + "enum": [ + "LocalSystem", + "DeviceCredentials", + "CustomCredentials" + ] + }, + "username": { + "type": "string", + "description": "The username (used with 'CustomCredentials' type)." + }, + "password": { + "type": "string", + "description": "The password (used with 'CustomCredentials' type)." + } + }, + "description": "Credentials for a remote execution task.", + "example": { + "type": "CustomCredentials", + "username": "admin", + "password": "pass" + } + }, + "ScheduledTaskParameter": { + "required": [ + "description", + "name", + "type" + ], + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The parameter name. The value must not be empty." + }, + "value": { + "type": "string", + "description": "The parameter value." + }, + "description": { + "type": "string", + "description": "The parameter name. The value must not be empty." + }, + "type": { + "type": "string", + "description": "The parameter type. Supported values: string, integer, boolean, text, dword, password. Use 'password' for sensitive information to ensure encryption and avoid plain text storage.", + "enum": [ + "string", + "integer", + "boolean", + "text", + "dword", + "password" + ] + } + }, + "description": "Input Parameters of the task to be executed, whether it is an Automation Policy, a script, a MAC script, etc.\nParameters for an automation policy are defined according to the script repository item associated with\na given scheduled task.\nFor a script or a MAC script, the whole command line can be specified using the parameter \"CommandLine\".\n", + "example": " {\n \"name\": \"CommandLine\",\n \"value\": \"killprocess.vbs /process:33022\",\n \"description\": \"Command line to execute\",\n \"type\": \"string\",\n }\n" + }, + "ScheduledTaskCreateResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TaskCreate" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Response for a task-creation request", + "example": { + "data": { + "taskId": 1985975 + }, + "_links": { + "task": "/api/scheduled-tasks/{1985975}" + } + } + }, + "TaskCreate": { + "type": "object", + "properties": { + "taskId": { + "type": "integer", + "format": "int32" + } + }, + "description": "Information about a newly created task", + "example": { + "taskId": 1985975 + } + }, + "PatchComparisonReportRequest": { + "required": [ + "startDate" + ], + "type": "object", + "properties": { + "installStatuses": { + "type": "array", + "items": { + "type": "string" + } + }, + "patchApprovals": { + "type": "array", + "items": { + "type": "string" + } + }, + "patchCategories": { + "type": "array", + "items": { + "type": "string" + } + }, + "startDate": { + "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])(T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(\\.\\d{3})?Z)?$", + "type": "string" + } + }, + "description": "Request for generating a patch comparison report.\ncustomerId: The ID of the customer for whom the report is to be generated.\nThe following fields are used to filter and customize the report:\ninstallStatuses: Aborted,Failed,In Progress,Installed,Installed With Errors,Not Installed\npatchApprovals: Approved for Install,Approved for Removal,Declined,Not Approved,No Approval\npatchCategories: Critical Updates,Update Rollups,Updates,Feature Packs,Definition Updates,\n Security Updates,Service Packs,Drivers,Tools,Third Party,Upgrades,Applications\nstartDate: The start date for the report in ISO 8601 format (e.g., \"2023-01-01\").\nIf any of the filtering fields are not provided, all the values will be used in filter.\n", + "example": { + "installStatuses": [ + "Installed", + "Not Installed" + ], + "patchApprovals": [ + "Approved for Install", + "No Approval" + ], + "patchCategories": [ + "Critical Updates", + "Security Updates" + ], + "startDate": "2023-01-01" + } + }, + "DmsLoginException": { + "type": "object", + "properties": { + "cause": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + }, + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "sensitiveMessage": { + "type": "string" + }, + "suppressed": { + "type": "array", + "items": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + } + }, + "localizedMessage": { + "type": "string" + } + }, + "description": "Exception indicating a failure to login to the DMS.", + "example": { + "status": "401", + "message": "[ID=2b85998f-26a3-467a] UNAUTHORIZED: DmsLoginException: Failed to get the sessionId. statusCode=401" + } + }, + "AccessDeniedException": { + "type": "object", + "properties": { + "cause": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + }, + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "suppressed": { + "type": "array", + "items": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + } + }, + "localizedMessage": { + "type": "string" + } + }, + "description": "Exception indicating access to a resource was denied.", + "example": { + "status": "403", + "message": "[ID=2b85998f-26a3-467a] FORBIDDEN: AccessDeniedException: You do not have permission to access this resource." + } + }, + "ResourceNotFoundException": { + "type": "object", + "properties": { + "cause": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + }, + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "suppressed": { + "type": "array", + "items": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + } + }, + "localizedMessage": { + "type": "string" + } + }, + "description": "Exception indicating a resource was not found.", + "example": { + "status": "404", + "message": "[ID=2b85998f-26a3-467a] NOT FOUND: ResourceNotFoundException: The requested resource was not found." + } + }, + "ApiServiceRuntimeException": { + "type": "object", + "properties": { + "cause": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + }, + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "suppressed": { + "type": "array", + "items": { + "type": "object", + "properties": { + "stackTrace": { + "type": "array", + "items": { + "type": "object", + "properties": { + "classLoaderName": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "moduleVersion": { + "type": "string" + }, + "methodName": { + "type": "string" + }, + "fileName": { + "type": "string" + }, + "lineNumber": { + "type": "integer", + "format": "int32" + }, + "className": { + "type": "string" + }, + "nativeMethod": { + "type": "boolean" + } + } + } + }, + "message": { + "type": "string" + }, + "localizedMessage": { + "type": "string" + } + } + } + }, + "localizedMessage": { + "type": "string" + } + }, + "description": "Base for API-service runtime exception.", + "example": { + "status": "500", + "message": "[ID=2b85998f-26a3-467a] INTERNAL SERVER ERROR: ApiServiceRuntimeException: An unexpected error occurred." + } + }, + "PatchComparisonReportResponse": { + "type": "object", + "properties": { + "reportId": { + "type": "integer", + "format": "int32" + }, + "reportStatus": { + "type": "string", + "enum": [ + "COMPLETED", + "IN_PROGRESS", + "FAILED", + "ABORTED" + ] + }, + "message": { + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/Data" + } + }, + "description": "Response for generating a patch comparison report.\nreportId: The unique identifier for the generated report.\nThe following fields provide additional information about the report generation status:\nreportStatus: The current status of the report generation (e.g., IN_PROGRESS, COMPLETED, FAILED).\nmessage: A message providing additional information about the report generation status.\ndata: The actual patch comparison report data, if generation is completed successfully.\nIf the report generation is still in progress or has failed, this field will be null.\n\nNOTE : To get the report data, the reportStatus should be COMPLETED.\nUse /api/ report/{reportId} to check the status of the report and retrieve the data when ready.\n", + "example": { + "reportId": 505005, + "reportStatus": "COMPLETED", + "data": { + "deviceClassSummaries": [ + { + "deviceClass": "Laptops - Windows", + "approvalStatusCounts": { + "noApproval": 10, + "approvedForInstall": 5 + } + }, + { + "deviceClass": "Workstations - Windows", + "approvalStatusCounts": { + "noApproval": 10, + "approvedForInstall": 5 + } + }, + { + "deviceClass": "Servers - Windows", + "approvalStatusCounts": { + "noApproval": 10, + "approvedForInstall": 5 + } + } + ], + "patchSummaryList": [ + { + "approvalStatus": "Approved for Install", + "patchInstallStatusCounts": [ + { + "patchInstallStatus": "Aborted", + "patchTypeSummaries": [ + { + "patchType": "definationUpdates", + "count": 2 + }, + { + "patchType": "servicePacks", + "count": 6 + } + ] + }, + { + "patchInstallStatus": "Failed", + "patchTypeSummaries": [ + { + "patchType": "definationUpdates", + "count": 2 + }, + { + "patchType": "servicePacks", + "count": 6 + } + ] + } + ] + } + ] + } + } + }, + "UserCreateRequest": { + "required": [ + "email", + "firstName", + "lastName", + "password" + ], + "type": "object", + "properties": { + "email": { + "type": "string" + }, + "password": { + "type": "string" + }, + "firstName": { + "maxLength": 50, + "minLength": 0, + "type": "string" + }, + "lastName": { + "maxLength": 50, + "minLength": 0, + "type": "string" + }, + "username": { + "maxLength": 50, + "minLength": 0, + "type": "string" + }, + "country": { + "type": "string" + }, + "postalCode": { + "pattern": "^[A-Za-z0-9](?:[ -]?[A-Za-z0-9]){1,11}$", + "type": "string" + }, + "street1": { + "maxLength": 100, + "minLength": 0, + "type": "string" + }, + "street2": { + "maxLength": 100, + "minLength": 0, + "type": "string" + }, + "city": { + "maxLength": 50, + "minLength": 0, + "type": "string" + }, + "state": { + "maxLength": 50, + "minLength": 0, + "type": "string" + }, + "telephone": { + "pattern": "^\\+?(?=(?:[^0-9]*[0-9]){7,15}[^0-9]*$)[0-9(][0-9\\s().-]*[0-9]$", + "type": "string" + }, + "ext": { + "pattern": "^\\d{1,6}$", + "type": "string" + }, + "department": { + "maxLength": 50, + "minLength": 0, + "type": "string" + }, + "notificationEmail": { + "type": "string" + }, + "status": { + "type": "string" + }, + "roleIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "accessGroupIds": { + "type": "array", + "items": { + "type": "string" + } + }, + "apiOnlyUser": { + "type": "boolean" + } + }, + "description": "Request for creating a new user.", + "example": { + "email": "user@example.com", + "password": "SecurePassword123!", + "firstName": "John", + "lastName": "Doe", + "username": "johndoe", + "country": "US", + "postalCode": "12345", + "street1": "123 Main St", + "street2": "Apt 4B", + "city": "Anytown", + "state": "CA", + "telephone": "+1234567890", + "ext": "123", + "department": "IT", + "notificationEmail": "notify@example.com", + "status": "enabled", + "roleIds": [ + "1", + "2" + ], + "accessGroupIds": [ + "10", + "20" + ], + "apiOnlyUser": false + } + }, + "UserCreateResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/Data" + } + }, + "description": "Response for user creation.", + "example": { + "status": 201, + "message": "User created successfully.", + "data": { + "userId": 12345 + } + } + }, + "CreateUserRoleRequest": { + "required": [ + "description", + "permissionIds", + "roleName" + ], + "type": "object", + "properties": { + "roleName": { + "type": "string", + "description": "The name of the role", + "example": "Admin" + }, + "description": { + "maxLength": 255, + "minLength": 0, + "type": "string", + "description": "The description of the role", + "example": "Admin role" + }, + "permissionIds": { + "type": "array", + "description": "The list of permissions", + "example": [ + 1, + 2, + 3 + ], + "items": { + "type": "string", + "description": "The list of permissions", + "example": "[1,2,3]" + } + }, + "userIds": { + "type": "array", + "description": "The list of user IDs", + "example": [ + 1, + 2, + 3 + ], + "items": { + "type": "string", + "description": "The list of user IDs", + "example": "[1,2,3]" + } + } + }, + "description": "Request Payload for adding a new user role.", + "example": { + "roleName": "Admin", + "description": "Admin role", + "permissionIds": [ + "1", + "2", + "3" + ], + "userIds": [ + "1", + "2", + "3" + ] + } + }, + "CreateUserRoleResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Data" + }, + "links": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "description": "Represents the response of creating a new role and contains the role ID for a newly created role.\n", + "example": { + "data": { + "roleId": 123 + }, + "_links": [] + } + }, + "DeviceAccessGroupCreateRequest": { + "required": [ + "groupDescription", + "groupName" + ], + "type": "object", + "properties": { + "groupName": { + "type": "string", + "description": "Name of the access group." + }, + "groupDescription": { + "type": "string", + "description": "Description of the access group." + }, + "deviceIds": { + "type": "array", + "description": "List of device IDs to attach to the access group.", + "items": { + "type": "string", + "description": "List of device IDs to attach to the access group." + } + }, + "userIds": { + "type": "array", + "description": "List of user IDs to be associated with the access group.", + "items": { + "type": "string", + "description": "List of user IDs to be associated with the access group." + } + } + }, + "description": "Request for creating a device type access group.", + "example": { + "groupName": "Example Group Name", + "groupDescription": "A sample access group for demonstration purposes", + "deviceIds": [ + "1001", + "1002" + ], + "userIds": [ + "5001", + "5002" + ] + } + }, + "OrgUnitTypeAccessGroupCreateRequest": { + "required": [ + "groupDescription", + "groupName" + ], + "type": "object", + "properties": { + "groupName": { + "type": "string", + "description": "Name of the access group." + }, + "groupDescription": { + "type": "string", + "description": "Description of the access group." + }, + "orgUnitIds": { + "type": "array", + "description": "List of orgUnit IDs to attach to the access group.", + "items": { + "type": "string", + "description": "List of orgUnit IDs to attach to the access group." + } + }, + "userIds": { + "type": "array", + "description": "List of user IDs to be associated with the access group.", + "items": { + "type": "string", + "description": "List of user IDs to be associated with the access group." + } + }, + "autoIncludeNewOrgUnits": { + "type": "string", + "description": "Flag indicating whether new org units should be automatically included. Default or invalid: false" + } + }, + "description": "Request for creating an org unit type access group.", + "example": { + "groupName": "Example Group Name", + "groupDescription": "A sample access group for demonstration purposes", + "orgUnitIds": [ + "1001", + "1002" + ], + "userIds": [ + "5001", + "5002" + ], + "autoIncludeNewOrgUnits": "true" + } + }, + "WindowsServiceActionRequest": { + "required": [ + "action", + "serviceNames" + ], + "type": "object", + "properties": { + "serviceNames": { + "maxItems": 100, + "minItems": 0, + "type": "array", + "description": "List of Windows service internal names (not display names) to act on.", + "example": [ + "Spooler", + "wuauserv" + ], + "items": { + "type": "string", + "description": "List of Windows service internal names (not display names) to act on.", + "example": "[\"Spooler\",\"wuauserv\"]" + } + }, + "action": { + "type": "string", + "description": "Action to perform on every listed service. Allowed values: Start, Stop, Restart, Pause, Resume.", + "example": "Stop" + } + }, + "description": "Request to perform a control action on one or more Windows Services on a managed device.", + "example": { + "serviceNames": [ + "Spooler", + "wuauserv" + ], + "action": "Stop" + } + }, + "ServiceResult": { + "type": "object", + "properties": { + "serviceName": { + "type": "string", + "description": "Windows service internal name.", + "example": "Spooler" + }, + "serviceStatus": { + "type": "string", + "description": "Status of the service after the action, e.g. \"Stopped\", \"Running\", \"Paused\".", + "example": "Stopped" + }, + "displayName": { + "type": "string", + "description": "Display name of the service.", + "example": "Print Spooler" + }, + "actionStatus": { + "type": "string", + "description": "Running state after the action, e.g. \"Stopped\", \"Running\", \"Paused\".", + "example": "Stopped" + }, + "actionDetails": { + "type": "string", + "description": "Additional details about the service actionStatus, if available.", + "example": "Service stopped successfully." + } + }, + "description": "State of a single Windows Service after the action." + }, + "WindowsServiceActionResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/WindowsServiceActionResult" + } + } + }, + "WindowsServiceActionResult": { + "type": "object", + "properties": { + "overallStatus": { + "type": "string", + "description": "Overall outcome reported by the device agent, e.g. \"Completed\", \"Error\", \"InProgress\".", + "example": "Completed", + "enum": [ + "Completed", + "CompletedWithError", + "Failed", + "InProgress", + "Created", + "NotCompleted", + "FailedTerminated", + "FailedCrashed", + "Unknown", + "Updated", + "Removed" + ] + }, + "services": { + "type": "array", + "description": "Per-service state after the action was applied.", + "items": { + "$ref": "#/components/schemas/ServiceResult" + } + } + }, + "description": "Result of a Windows Service control action." + }, + "RemoteControlTaskRequest": { + "type": "object", + "properties": { + "remoteControlType": { + "type": "string", + "description": "The remote-control adapter type. If omitted, the server resolves the effective type from device configuration.", + "enum": [ + "SSH", + "VNC", + "RDP", + "MSPAnywhere", + "Telnet" + ] + }, + "description": { + "maxLength": 500, + "minLength": 0, + "type": "string", + "description": "Free-text reason for the remote-control session; surfaced in audit/history." + }, + "port": { + "type": "integer", + "description": "Optional override port for the RC session.", + "format": "int32" + } + }, + "description": "Request body for creating a remote-control task. All fields are optional. If remoteControlType is omitted, N-Central determines the type from device configuration.", + "example": { + "remoteControlType": "SSH", + "description": "Troubleshooting network connectivity issue" + } + }, + "ConnectionDetails": { + "type": "object", + "properties": { + "port": { + "type": "integer", + "description": "The port number for the connection.", + "format": "int32", + "nullable": true + }, + "protocol": { + "type": "string", + "description": "The protocol being used (e.g., RDP, SSH, VNC, Telnet).", + "nullable": true + }, + "encryptionEnabled": { + "type": "boolean", + "description": "Whether encryption is enabled for the connection.", + "nullable": true + } + }, + "description": "Connection details for remote control sessions.", + "nullable": true + }, + "MspaConfiguration": { + "type": "object", + "properties": { + "uuid": { + "type": "string", + "description": "The MSPAnywhere device UUID.", + "nullable": true + }, + "secretKey": { + "type": "string", + "description": "The encrypted secret key.", + "nullable": true + }, + "username": { + "type": "string", + "description": "The username for the session.", + "nullable": true + }, + "usePeerToPeer": { + "type": "boolean", + "description": "Whether to use peer-to-peer connection.", + "nullable": true + }, + "monitorOnly": { + "type": "boolean", + "description": "Whether the session is monitor-only (view only).", + "nullable": true + }, + "visualIndicator": { + "type": "boolean", + "description": "Whether to show visual indicator on remote device.", + "nullable": true + } + }, + "description": "MSPAnywhere/Take Control configuration for remote control connections.", + "nullable": true + }, + "RemoteControlTaskCreatedResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RemoteControlTaskData" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related resources." + }, + "description": "Links to related resources." + } + }, + "description": "Response for a remote-control task creation request.", + "example": { + "data": { + "remoteControlTaskId": 711902314, + "sessionUuid": "a54bd852-7ce8-4a19-9a68-bab7628c06a4", + "deviceId": 1234567890, + "applianceId": 1926184289, + "connectionType": "SSH", + "status": "CREATED", + "sshTunnelConfiguration": { + "centralServerIp": "fsp-nc-6951.aws.n-able.com,34.220.84.242", + "centralServerUsername": "rc_test123", + "forwardedPort": 10510 + }, + "connectionDetails": { + "port": 10510, + "protocol": "SSH" + } + }, + "_links": { + "device": "/api/devices/1234567890" + } + } + }, + "RemoteControlTaskData": { + "type": "object", + "properties": { + "remoteControlTaskId": { + "type": "integer", + "description": "The server-assigned remote-control task ID.", + "format": "int32" + }, + "sessionUuid": { + "type": "string", + "description": "The unique session UUID for this remote control session.", + "nullable": true + }, + "deviceId": { + "type": "integer", + "description": "The target device ID.", + "format": "int32" + }, + "applianceId": { + "type": "integer", + "description": "The appliance ID handling the connection.", + "format": "int32", + "nullable": true + }, + "connectionType": { + "type": "string", + "description": "The resolved connection type.", + "nullable": true, + "enum": [ + "SSH", + "VNC", + "RDP", + "MSPAnywhere", + "Telnet" + ] + }, + "status": { + "type": "string", + "description": "The initial task status.", + "nullable": true + }, + "downloadUrl": { + "type": "string", + "description": "The download URL for remote control connector setup.", + "nullable": true + }, + "tunnelConfiguration": { + "$ref": "#/components/schemas/TunnelConfiguration" + }, + "sshTunnelConfiguration": { + "$ref": "#/components/schemas/SshTunnelConfiguration" + }, + "mspaConfiguration": { + "$ref": "#/components/schemas/MspaConfiguration" + }, + "connectionDetails": { + "$ref": "#/components/schemas/ConnectionDetails" + } + }, + "description": "The created remote-control task details." + }, + "SshTunnelConfiguration": { + "type": "object", + "properties": { + "centralServerIp": { + "type": "string", + "description": "The central server IP address and hostname (e.g., 'hostname,ip').", + "nullable": true + }, + "centralServerUsername": { + "type": "string", + "description": "The SSH username for the central server.", + "nullable": true + }, + "forwardedPort": { + "type": "integer", + "description": "The primary forwarded port on the central server.", + "format": "int32", + "nullable": true + }, + "forwardedPort2": { + "type": "integer", + "description": "The secondary forwarded port (optional, -1 if not used).", + "format": "int32", + "nullable": true + }, + "vncPasswordSetting": { + "type": "string", + "description": "The VNC password setting (e.g., SetTemporary).", + "nullable": true + }, + "connectionTimeout": { + "type": "integer", + "description": "The connection timeout in minutes.", + "format": "int32", + "nullable": true + }, + "vproAccount": { + "type": "string", + "description": "The vPro account username (optional).", + "nullable": true + } + }, + "description": "SSH/VNC tunnel configuration for remote control connections through a central server. Passwords are not included in the response for security reasons.", + "nullable": true + }, + "TunnelConfiguration": { + "type": "object", + "properties": { + "stunServer": { + "type": "string", + "description": "The STUN server address and port (e.g., stun1.n-able.com:3478).", + "nullable": true + }, + "tunnelServerUrl": { + "type": "string", + "description": "The tunnel server URL (e.g., https://tunnel.n-able.com:443).", + "nullable": true + } + }, + "description": "Tunnel configuration for remote control connections.", + "nullable": true + }, + "AddNoteRequest": { + "required": [ + "note", + "userId" + ], + "type": "object", + "properties": { + "userId": { + "type": "integer", + "description": "The ID of the user adding the note.", + "format": "int32", + "example": 123 + }, + "note": { + "maxLength": 32000, + "minLength": 0, + "type": "string", + "description": "The content of the note", + "example": "Device maintenance completed" + }, + "insertionTime": { + "type": "string", + "description": "The timestamp for the note. If not provided, the server will use the current time.", + "format": "date-time", + "example": "2024-01-15T10:30:00Z" + } + }, + "description": "Request body for adding a note to a device" + }, + "AddNoteResponse": { + "type": "object", + "properties": { + "deviceId": { + "type": "integer", + "description": "The ID of the device the note was added to", + "format": "int32", + "example": 12345 + }, + "message": { + "type": "string", + "description": "Status message indicating the result", + "example": "Note added successfully" + } + }, + "description": "Response after successfully adding a note to a device" + }, + "AddBatchNoteRequest": { + "required": [ + "deviceIds", + "note", + "userId" + ], + "type": "object", + "properties": { + "deviceIds": { + "type": "array", + "description": "List of device IDs to add the note to.", + "example": [ + 1001, + 1002, + 1003 + ], + "items": { + "type": "integer", + "description": "List of device IDs to add the note to.", + "format": "int32" + } + }, + "userId": { + "type": "integer", + "description": "The ID of the user adding the note.", + "format": "int32", + "example": 123 + }, + "note": { + "maxLength": 32000, + "minLength": 0, + "type": "string", + "description": "The content of the note", + "example": "Device maintenance completed" + }, + "insertionTime": { + "type": "string", + "description": "The timestamp for the note. If not provided, the server will use the current time.", + "format": "date-time", + "example": "2024-01-15T10:30:00Z" + } + }, + "description": "Request body for adding a note to multiple devices" + }, + "AddBatchNoteResponse": { + "type": "object", + "properties": { + "deviceIds": { + "type": "array", + "description": "The IDs of the devices the note was added to", + "example": [ + 1001, + 1002, + 1003 + ], + "items": { + "type": "integer", + "description": "The IDs of the devices the note was added to", + "format": "int32" + } + }, + "message": { + "type": "string", + "description": "Status message indicating the result", + "example": "Note added successfully" + } + }, + "description": "Response after successfully adding a note to multiple devices" + }, + "MaintenanceWindowsRequest": { + "type": "object", + "properties": { + "deviceIDs": { + "type": "array", + "items": { + "type": "integer", + "format": "int32" + } + }, + "maintenanceWindows": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MaintenanceWindowRequest" + } + } + }, + "description": "Request for creating a set of maintenance Windows to a list of devices.", + "example": { + "deviceIDs": [ + 123456789, + 234567890, + 345678901 + ], + "maintenanceWindows": [ + { + "applicableAction": [ + { + "type": "Patch", + "actions": [ + { + "Key": "detect", + "Value": null + } + ] + } + ], + "name": "Test Maintenance Window", + "type": "action", + "cron": "0 0 0 ? 2 1,4 *", + "duration": 60, + "enabled": true, + "maxDowntime": 0, + "rebootMethod": "allowUserToPostpone", + "rebootDelay": 0, + "downtimeOnAction": false, + "userMessageEnabled": false, + "userMessage": null, + "messageSenderEnabled": false, + "messageSender": null, + "preserveStateEnabled": false + } + ] + } + }, + "DeviceAddRequest": { + "required": [ + "customerId", + "deviceClass", + "longName", + "networkAddress", + "supportedOs", + "{\n \"customerId\",\n \"networkAddress\",\n \"longName\",\n \"supportedOs\",\n \"deviceClass\"\n}" + ], + "type": "object", + "properties": { + "customerId": { + "type": "string", + "description": "ID of the customer to which the device belongs", + "example": "12345" + }, + "networkAddress": { + "type": "string", + "description": "Network address of the device, which can be a URI or IP address", + "example": "192.168.4.3" + }, + "description": { + "maxLength": 255, + "minLength": 0, + "type": "string", + "description": "Brief description of the device", + "example": "New device description" + }, + "supportedOs": { + "type": "string", + "description": "Operating system supported by the device", + "example": "Windows" + }, + "longName": { + "type": "string", + "description": "Long name of the device", + "example": "Device Long Name" + }, + "licenseMode": { + "maxLength": 255, + "minLength": 0, + "type": "string", + "description": "License mode of the device", + "example": "Standard" + }, + "deviceClass": { + "type": "string", + "description": "Class of the device", + "example": "Router" + }, + "macAddress": { + "type": "string", + "description": "MAC address of the device", + "example": "00:1A:2B:3C:4D:5E" + }, + "username": { + "maxLength": 255, + "minLength": 0, + "type": "string", + "description": "Username for device authentication", + "example": "admin" + }, + "password": { + "maxLength": 255, + "minLength": 0, + "type": "string", + "description": "Password for device authentication", + "example": "password123" + } + }, + "description": "Request to add a new device", + "example": { + "customerId": "12345", + "networkAddress": "1.2.3.4", + "description": "New device description", + "supportedOs": "Windows", + "longName": "Device Long Name", + "licenseMode": "Standard", + "deviceClass": "Router", + "macAddress": "00:1A:2B:3C:4D:5E", + "username": "admin", + "password": "password123" + } + }, + "DeviceAddResponse": { + "type": "object", + "properties": { + "deviceId": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + } + }, + "description": "Response after adding a new device", + "example": { + "deviceId": 12345, + "message": "Some message about the device addition." + } + }, + "GenerateSoftwareDownloadRequest": { + "type": "object", + "properties": { + "softwareId": { + "pattern": "^[1-9]\\d*$", + "type": "string" + } + }, + "description": "Request to generate a software download link.", + "example": { + "softwareId": 123 + } + }, + "GenerateSoftwareDownloadLinkResponse": { + "type": "object", + "properties": { + "downloadLink": { + "type": "string" + }, + "expirationDate": { + "type": "string" + } + } + }, + "SiteCreation": { + "required": [ + "siteName" + ], + "type": "object", + "properties": { + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "siteName": { + "type": "string", + "description": "Name of the site." + }, + "licenseType": { + "type": "string", + "description": "License type of the site.", + "default": "Professional" + } + }, + "description": "Data object for site.", + "example": { + "siteName": "New site name", + "contactFirstName": "first name", + "contactLastName": "last name", + "licenseType": "Professional", + "externalId": "extId", + "phone": "phone", + "contactTitle": "contact title", + "contactEmail": "contact@email.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "postalCode": "A1A 1A1" + } + }, + "SiteCreated": { + "type": "object", + "properties": { + "siteId": { + "type": "integer", + "description": "Id of the created site.", + "format": "int32" + } + } + }, + "CustomPsaTicketCreateRequest": { + "required": [ + "psaCustomTicketId", + "ticketNumber", + "ticketUrl" + ], + "type": "object", + "properties": { + "psaCustomTicketId": { + "type": "integer", + "description": "The ID of the custom PSA ticket provide by N-central.", + "format": "int32" + }, + "ticketNumber": { + "type": "string", + "description": "The external ticket number linked to the custom PSA ticket." + }, + "ticketUrl": { + "pattern": "^https?://.+", + "type": "string", + "description": "The external ticket URL linked to the custom PSA ticket." + } + }, + "description": "Request for creating a custom PSA ticket.", + "example": { + "psaCustomTicketId": 123, + "ticketNumber": "EXT-456", + "ticketUrl": "https://example.com/ticket/EXT-456" + } + }, + "CustomPsaTicket": { + "type": "object", + "properties": { + "inconsistencyDetected": { + "type": "boolean" + }, + "lastStatus": { + "type": "string" + }, + "lastStatusTimestamp": { + "type": "string" + }, + "newConfirmedStatus": { + "type": "string" + }, + "psaCustomTicketId": { + "type": "integer", + "format": "int32" + }, + "psaTicketNumber": { + "type": "string" + }, + "ticketCreationDate": { + "type": "string" + }, + "url": { + "type": "string" + } + } + }, + "CustomPsaTicketCreateResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/CustomPsaTicket" + } + }, + "description": "Response for creating a custom PSA ticket.", + "example": { + "status": 200, + "message": "Custom PSA ticket created successfully.", + "data": { + "inconsistencyDetected": false, + "lastStatus": "Open", + "lastStatusTimestamp": "2024-06-01T12:00:00Z", + "newConfirmedStatus": "Open", + "psaCustomTicketId": 12345, + "psaTicketNumber": "CPT-67890", + "ticketCreationDate": "2024-06-01T12:00:00Z", + "url": "https://example.com/tickets/CPT-67890" + } + } + }, + "CustomPsaTicketGetResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CustomPsaTicketInfo" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Represents the response for fetching details of a specific Custom PSA ticket.\n", + "example": { + "data": { + "ticketId": "1142285696", + "ticketTitle": "Foo bar ticket #1", + "ticketDetails": "For testing PSA ticketing", + "ticketStatus": "CREATE_TICKET_CREATED_IN_NCENTRAL", + "creationDate": "2024-02-21T06:28:10.624-05:00[America/New_York]" + }, + "_links": {} + } + }, + "CustomPsaTicketInfo": { + "type": "object", + "properties": { + "ticketId": { + "type": "string", + "description": "The ID of the Custom PSA ticket." + }, + "ticketTitle": { + "type": "string", + "description": "The title of the Custom PSA ticket." + }, + "ticketDetails": { + "type": "string", + "description": "The details of the Custom PSA ticket." + }, + "ticketStatus": { + "type": "string", + "description": "The status of the Custom PSA ticket." + }, + "creationDate": { + "type": "string", + "description": "The creation date of the Custom PSA ticket." + } + }, + "description": "Represents the response for fetching details of a specific Custom PSA ticket." + }, + "CustomPsaTicketResolveResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/CustomPsaTicket" + } + } + }, + "CustomPsaTicketReopenResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "format": "int32" + }, + "message": { + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/CustomPsaTicket" + } + }, + "description": "Response for reopening a custom PSA ticket", + "example": { + "status": 200, + "message": "Custom PSA ticket reopened successfully", + "data": { + "psaCustomTicketId": 12345, + "psaTicketNumber": "PSA-67890", + "ticketCreationDate": "2024-06-01T12:34:56Z", + "lastStatus": "Reopened", + "lastStatusTimestamp": "2024-06-10T15:00:00Z", + "url": "https://ncentral.example.com/tickets/12345" + } + } + }, + "AuthToken": { + "required": [ + "token", + "type" + ], + "type": "object", + "properties": { + "token": { + "type": "string", + "description": "The JWT token." + }, + "type": { + "type": "string", + "description": "The token type: bearer or body." + }, + "expirySeconds": { + "type": "integer", + "description": "The expiry in seconds.", + "format": "int64" + } + }, + "description": "Authentication token (access or refresh).", + "example": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1MjZjMTjI0M30.try6YwSXhu1qh1iyBPonWVfxLexlNavXkRqQaeY2uzo", + "type": "Bearer", + "expirySeconds": 3600 + } + }, + "AuthTokens": { + "required": [ + "access", + "refresh" + ], + "type": "object", + "properties": { + "access": { + "$ref": "#/components/schemas/AuthToken" + }, + "refresh": { + "$ref": "#/components/schemas/AuthToken" + } + }, + "description": "Authentication tokens (access and refresh).", + "example": { + "access": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1MjZjMTjI0M30.try6YwSXhu1qh1iyBPonWVfxLexlNavXkRqQaeY2uzo", + "type": "Bearer", + "expirySeconds": 3600 + }, + "refresh": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1I2OTQ0M30.T_yn88Xg258liJa5AwLq011-TWDMWMKVVyR5AYOM3os", + "type": "Body", + "expirySeconds": 90000 + } + } + }, + "AuthenticateResponse": { + "type": "object", + "properties": { + "tokens": { + "$ref": "#/components/schemas/AuthTokens" + }, + "refresh": { + "type": "string" + }, + "validate": { + "type": "string" + } + }, + "description": "Response for obtaining the authentication tokens.", + "example": { + "tokens": { + "access": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1MjZjMTjI0M30.try6YwSXhu1qh1iyBPonWVfxLexlNavXkRqQaeY2uzo", + "type": "Bearer", + "expirySeconds": 3600 + }, + "refresh": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1I2OTQ0M30.T_yn88Xg258liJa5AwLq011-TWDMWMKVVyR5AYOM3os", + "type": "Body", + "expirySeconds": 90000 + } + }, + "refresh": "/api/auth/refresh", + "validate": "/api/auth/validate" + } + }, + "AuthRefreshResponse": { + "type": "object", + "properties": { + "tokens": { + "$ref": "#/components/schemas/AuthTokens" + }, + "refresh": { + "type": "string" + }, + "validate": { + "type": "string" + } + }, + "description": "Response for the refresh of authentication tokens.", + "example": { + "tokens": { + "access": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1MjZjMTjI0M30.try6YwSXhu1qh1iyBPonWVfxLexlNavXkRqQaeY2uzo", + "type": "Bearer", + "expirySeconds": 3600 + }, + "refresh": { + "token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI1I2OTQ0M30.T_yn88Xg258liJa5AwLq011-TWDMWMKVVyR5AYOM3os", + "type": "Body", + "expirySeconds": 90000 + } + }, + "refresh": "/api/auth/refresh", + "validate": "/api/auth/validate" + } + }, + "ModifyCustomerLimitRequest": { + "type": "object", + "properties": { + "limitName": { + "type": "string" + }, + "value": { + "type": "integer", + "format": "int32" + }, + "maxValue": { + "type": "integer", + "format": "int32" + } + }, + "description": "Represents a customer limit. Please note that 'maxValue' is not modifiable.", + "example": { + "limitName": "DeviceLimit", + "value": 100 + } + }, + "CustomerLimitResponseEntity": { + "type": "object", + "properties": { + "limitName": { + "type": "string" + }, + "value": { + "type": "integer", + "format": "int32" + }, + "maxValue": { + "type": "integer", + "format": "int32" + } + } + }, + "ModifyCustomerLimitsResponse": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerLimitResponseEntity" + } + } + }, + "description": "Response for modifying customer limits", + "example": { + "message": "Customer limits modified successfully.", + "data": [ + { + "limitName": "MaxUsers", + "value": 150, + "maxValue": 300 + }, + { + "limitName": "MaxDevices", + "value": 600, + "maxValue": 1200 + } + ] + } + }, + "AssetLifecyclePatchRequest": { + "type": "object", + "properties": { + "warrantyExpiryDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "leaseExpiryDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "expectedReplacementDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "purchaseDate": { + "pattern": "(\\d{4}-\\d{2}-\\d{2}( \\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?)?)?", + "type": "string" + }, + "cost": { + "type": "number" + }, + "location": { + "type": "string" + }, + "assetTag": { + "type": "string" + }, + "description": { + "type": "string" + }, + "updateWarrantyError": { + "type": "string" + } + }, + "description": "Asset Lifecycle Patch Request details", + "example": { + "warrantyExpiryDate": "2022-12-31", + "leaseExpiryDate": "2022-12-31", + "expectedReplacementDate": "2022-12-31", + "purchaseDate": "2022-12-31", + "cost": 0.0, + "location": "location", + "assetTag": "assetTag", + "description": "description", + "updateWarrantyError": "updateWarrantyError" + } + }, + "LinksResponse": { + "type": "object", + "properties": { + "_links": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + }, + "UserSelf": { + "type": "object", + "properties": { + "userId": { + "type": "integer", + "description": "The unique identifier of the user.", + "format": "int32", + "example": 1234567890 + }, + "customerId": { + "type": "integer", + "description": "The customer ID associated with the user.", + "format": "int32", + "example": 101 + }, + "username": { + "type": "string", + "description": "The username (email) of the user.", + "example": "johndoe@example.com" + }, + "title": { + "type": "string", + "description": "The title of the user.", + "example": "Mr" + }, + "firstName": { + "type": "string", + "description": "The first name of the user.", + "example": "John" + }, + "lastName": { + "type": "string", + "description": "The last name of the user.", + "example": "Doe" + }, + "email": { + "type": "string", + "description": "The primary email address of the user.", + "example": "johndoe@example.com" + }, + "phone": { + "type": "string", + "description": "The primary phone number of the user.", + "example": "555-1234" + }, + "extension": { + "type": "string", + "description": "The phone extension of the user.", + "example": "100" + }, + "department": { + "type": "string", + "description": "The department of the user.", + "example": "IT" + }, + "street1": { + "type": "string", + "description": "The first line of the user's street address.", + "example": "123 Main St" + }, + "street2": { + "type": "string", + "description": "The second line of the user's street address.", + "example": "Suite 200" + }, + "city": { + "type": "string", + "description": "The city of the user's address.", + "example": "Toronto" + }, + "stateProv": { + "type": "string", + "description": "The state or province of the user's address.", + "example": "ON" + }, + "country": { + "type": "string", + "description": "The country of the user's address.", + "example": "CA" + }, + "postalCode": { + "type": "string", + "description": "The postal code of the user's address.", + "example": "M5V 1A1" + }, + "isEnabled": { + "type": "boolean", + "description": "Indicates if the user account is enabled.", + "example": true + }, + "isLocked": { + "type": "boolean", + "description": "Indicates if the user account is locked.", + "example": false + }, + "isPasswordExpired": { + "type": "boolean", + "description": "Indicates if the user's password has expired.", + "example": false + }, + "isPasswordResetRequired": { + "type": "boolean", + "description": "Indicates if the user is required to reset their password.", + "example": false + }, + "autoSOPower": { + "type": "boolean", + "description": "Indicates if the user has automatic SO power admin rights.", + "example": false + }, + "autoSOUser": { + "type": "boolean", + "description": "Indicates if the user has automatic SO user rights.", + "example": false + }, + "isLDAP": { + "type": "boolean", + "description": "Indicates if the user is managed through LDAP.", + "example": false + }, + "ncompassEnabled": { + "type": "boolean", + "description": "Indicates if N-compass is enabled for the user.", + "example": false + }, + "twoFactorType": { + "type": "string", + "description": "The current two-factor authentication type for the user.", + "example": "NONE" + }, + "previousTwoFactorType": { + "type": "string", + "description": "The previous two-factor authentication type for the user.", + "example": "NONE" + }, + "externallyProvisioned": { + "type": "boolean", + "description": "Indicates if the user was externally provisioned.", + "example": false + }, + "generation": { + "type": "integer", + "description": "The customer hierarchy level (0=System, 1=SO, 2=Customer, 3=Site).", + "format": "int32", + "example": 1 + } + }, + "description": "Represents the authenticated user's profile information returned by GET /api/users/me.", + "example": { + "userId": 1234567890, + "customerId": 101, + "username": "johndoe@example.com", + "title": "Mr", + "firstName": "John", + "lastName": "Doe", + "email": "johndoe@example.com", + "phone": "555-1234", + "extension": "100", + "department": "IT", + "street1": "123 Main St", + "street2": "Suite 200", + "city": "Toronto", + "stateProv": "ON", + "country": "CA", + "postalCode": "M5V 1A1", + "isEnabled": true, + "isLocked": false, + "isPasswordExpired": false, + "isPasswordResetRequired": false, + "autoSOPower": false, + "autoSOUser": false, + "isLDAP": false, + "ncompassEnabled": false, + "twoFactorType": "NONE", + "previousTwoFactorType": "NONE", + "externallyProvisioned": false, + "generation": 1 + } + }, + "UserSelfResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "The HTTP status code.", + "format": "int32", + "example": 200 + }, + "message": { + "type": "string", + "description": "A human-readable message describing the result.", + "example": "User profile retrieved successfully." + }, + "data": { + "$ref": "#/components/schemas/UserSelf" + } + }, + "description": "Wrapper response for the authenticated user's profile information.", + "example": { + "status": 200, + "message": "User profile retrieved successfully.", + "data": { + "userId": 1234567890, + "customerId": 101, + "username": "johndoe@example.com", + "title": "Mr", + "firstName": "John", + "lastName": "Doe", + "email": "johndoe@example.com", + "phone": "555-1234", + "extension": "100", + "department": "IT", + "street1": "123 Main St", + "street2": "Suite 200", + "city": "Toronto", + "stateProv": "ON", + "country": "CA", + "postalCode": "M5V 1A1", + "isEnabled": true, + "isLocked": false, + "isPasswordExpired": false, + "isPasswordResetRequired": false, + "autoSOPower": false, + "autoSOUser": false, + "isLDAP": false, + "ncompassEnabled": false, + "twoFactorType": "NONE", + "previousTwoFactorType": "NONE", + "externallyProvisioned": false, + "generation": 1 + } + } + }, + "PsaCompany": { + "type": "object", + "properties": { + "psaCompanyId": { + "type": "integer", + "format": "int32" + }, + "psaCompanyName": { + "type": "string" + } + } + }, + "PsaSite": { + "type": "object", + "properties": { + "psaSiteId": { + "type": "integer", + "format": "int32" + }, + "psaSiteName": { + "type": "string" + } + }, + "description": "PSA Site details", + "example": { + "psaSiteId": 131415, + "psaSiteName": "Main Office" + } + }, + "PsaContact": { + "type": "object", + "properties": { + "psaContactId": { + "type": "integer", + "format": "int32" + }, + "psaContactName": { + "type": "string" + } + }, + "description": "PSA Contact details", + "example": { + "psaContactId": 123, + "psaContactName": "John Doe" + } + }, + "ListResponseSite": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Site" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "Site": { + "type": "object", + "properties": { + "siteId": { + "type": "string", + "description": "The ID of the organization unit." + }, + "siteName": { + "type": "string", + "description": "The name of the organization unit." + }, + "orgUnitType": { + "type": "string", + "description": "The type of the organization unit (SYSTEM, SO, CUSTOMER or SITE)." + }, + "parentId": { + "type": "string", + "description": "The ID of the parent organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "externalId2": { + "type": "string", + "description": "The external ID 2 of the organization unit." + }, + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "generation": { + "type": "integer", + "description": "The generation (depth in the customer hierarchy) of the customer.", + "format": "int32" + }, + "descendantCount": { + "type": "integer", + "description": "The number of direct (immediate-children) descendants of the customer.", + "format": "int32" + }, + "isSystem": { + "type": "boolean" + }, + "isServiceOrg": { + "type": "boolean" + } + }, + "description": "Data object for service organiztion organization.", + "example": { + "siteId": "100", + "siteName": "N-able", + "orgUnitType": "SO", + "parentId": "50", + "externalId": "extId", + "externalId2": "extId2", + "phone": "phone", + "contactTitle": "contact title", + "contactFirstName": "contact first name", + "contactLastName": "contact last name", + "contactEmail": "contact@email.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "county": null, + "postalCode": "A1A 1A1" + } + }, + "RegistrationToken": { + "type": "object", + "properties": { + "registrationToken": { + "type": "string", + "description": "The registration-token date.", + "example": "2f64ee5e-7c37-dce7-ffd2-d32912609623" + }, + "registrationTokenExpiryDate": { + "type": "string", + "description": "The registration-token expiry date.", + "example": "2024-05-01T23:59:00-04:00[America/New_York]" + } + }, + "description": "Represents the response for a registration token (GET endpoint).", + "example": { + "registrationToken": "2f64ee5e-7c37-dce7-ffd2-d32912609623", + "registrationTokenExpiryDate": "2024-05-01T23:59:00-04:00[America/New_York]" + } + }, + "RegistrationTokenGetResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/RegistrationToken" + } + } + }, + "ListResponseServiceOrganization": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ServiceOrganization" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "ServiceOrganization": { + "type": "object", + "properties": { + "soId": { + "type": "string", + "description": "The ID of the organization unit." + }, + "soName": { + "type": "string", + "description": "The name of the organization unit." + }, + "orgUnitType": { + "type": "string", + "description": "The type of the organization unit (SYSTEM, SO, CUSTOMER or SITE)." + }, + "parentId": { + "type": "string", + "description": "The ID of the parent organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "externalId2": { + "type": "string", + "description": "The external ID 2 of the organization unit." + }, + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "generation": { + "type": "integer", + "description": "The generation (depth in the customer hierarchy) of the customer.", + "format": "int32" + }, + "descendantCount": { + "type": "integer", + "description": "The number of direct (immediate-children) descendants of the customer.", + "format": "int32" + }, + "isSystem": { + "type": "boolean" + }, + "isServiceOrg": { + "type": "boolean" + } + }, + "description": "Data object for service organization.", + "example": { + "soId": "100", + "soName": "N-able", + "orgUnitType": "SO", + "parentId": "50", + "externalId": "extId", + "externalId2": "extId2", + "phone": "phone", + "contactTitle": "contact title", + "contactFirstName": "contact first name", + "contactLastName": "contact last name", + "contactEmail": "contact@email.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "county": null, + "postalCode": "A1A 1A1" + } + }, + "Customer": { + "type": "object", + "properties": { + "customerId": { + "type": "string", + "description": "The ID of the organization unit." + }, + "customerName": { + "type": "string", + "description": "The name of the organization unit." + }, + "orgUnitType": { + "type": "string", + "description": "The type of the organization unit (SYSTEM, SO, CUSTOMER or SITE)." + }, + "parentId": { + "type": "string", + "description": "The ID of the parent organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "externalId2": { + "type": "string", + "description": "The external ID 2 of the organization unit." + }, + "generation": { + "type": "integer", + "description": "The generation (depth in the customer hierarchy) of the customer.", + "format": "int32" + }, + "descendantCount": { + "type": "integer", + "description": "The number of direct (immediate-children) descendants of the customer.", + "format": "int32" + }, + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "county": { + "type": "string", + "description": "DEPRECATED: County where the organization unit is located." + }, + "isSystem": { + "type": "boolean" + }, + "isServiceOrg": { + "type": "boolean" + } + }, + "description": "Data object for service customer.", + "example": { + "customerId": "100", + "customerName": "N-able", + "orgUnitType": "SO", + "parentId": "50", + "externalId": "extId", + "externalId2": "extId2", + "phone": "phone", + "contactTitle": "contact title", + "contactFirstName": "contact first name", + "contactLastName": "contact last name", + "contactEmail": "contact@email.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "county": null, + "postalCode": "A1A 1A1" + } + }, + "ListResponseCustomer": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Customer" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "AuthValidateResponse": { + "type": "object", + "properties": { + "message": { + "type": "string" + } + }, + "description": "Response for validating the authentication access token.", + "example": { + "message": "The token is valid." + } + }, + "ServerTimeInfo": { + "type": "object", + "properties": { + "serverTime": { + "type": "string", + "description": "The server's current date and time in ISO-8601 format with offset", + "example": "2026-02-26T15:15:30-05:00" + }, + "timezone": { + "type": "string", + "description": "The server's IANA timezone identifier", + "example": "America/New_York" + }, + "utcOffset": { + "type": "string", + "description": "The server's UTC offset", + "example": "-05:00" + } + }, + "description": "Server time information including current time, timezone, and UTC offset" + }, + "ScheduledTaskInfoResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TaskInfo" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Task information response.", + "example": { + "data": { + "taskId": 905592865, + "parentId": 120, + "name": "Name", + "itemId": 2, + "type": "Script", + "orgUnitId": 100, + "soId": 50, + "siteId": null, + "applianceId": 1258095675, + "isReactive": false, + "isEnabled": true, + "deviceIds": [ + "1234567890" + ] + }, + "_links": { + "status": "/api/scheduled-tasks/905592865/status" + } + } + }, + "TaskInfo": { + "type": "object", + "properties": { + "taskId": { + "type": "integer", + "description": "Id of the task.", + "format": "int32" + }, + "parentId": { + "type": "integer", + "description": "The unique identifier of the parent task (if applicable), or null if there is no parent task.", + "format": "int32" + }, + "name": { + "type": "string", + "description": "The name of the task (same with taskName)." + }, + "taskName": { + "type": "string", + "description": "The name of the task (same with name)." + }, + "itemId": { + "type": "integer", + "description": "The unique identifier for the item associated with the task.", + "format": "int32" + }, + "type": { + "type": "string", + "description": "The type of the task." + }, + "orgUnitId": { + "type": "integer", + "description": "The unique identifier of the organization associated with the task.", + "format": "int32" + }, + "soId": { + "type": "integer", + "description": "The unique identifier of the SO associated with the task.", + "format": "int32" + }, + "customerId": { + "type": "integer", + "description": "The unique identifier of the customer associated with the task.", + "format": "int32" + }, + "siteId": { + "type": "integer", + "description": "The unique identifier of the site associated with the task.", + "format": "int32" + }, + "applianceId": { + "type": "integer", + "description": "The unique identifier of the appliance related to the task.", + "format": "int32" + }, + "isReactive": { + "type": "boolean", + "description": "Indicates whether the task is reactive (true) or not (false)." + }, + "isEnabled": { + "type": "boolean", + "description": "Indicates whether the task is enabled (true) or disabled (false)." + }, + "deviceIds": { + "type": "array", + "description": "List of device IDs that this task is run on.", + "items": { + "type": "string", + "description": "List of device IDs that this task is run on." + } + } + }, + "description": "Task information response.", + "example": { + "taskId": 905592865, + "parentId": 120, + "name": "Name", + "taskName": "Name", + "itemId": 2, + "type": "Script", + "orgUnitId": 100, + "soId": 50, + "customerId": 100, + "siteId": null, + "applianceId": 1258095675, + "isReactive": false, + "isEnabled": true, + "deviceIds": [ + "1234567890" + ] + } + }, + "ScheduledTaskAggregatedStatusResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/TaskAggregatedStatus" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Aggregated status response.", + "example": { + "data": { + "taskName": "Task Name", + "statusCounts": { + "Completed": 3, + "In Pending": 2 + } + }, + "_links": { + "details": "/api/scheduled-tasks/{taskId}/status/details" + } + } + }, + "TaskAggregatedStatus": { + "type": "object", + "properties": { + "taskName": { + "type": "string", + "description": "Name of the task." + }, + "statusCounts": { + "type": "object", + "additionalProperties": { + "type": "integer", + "description": "Map of status counts where keys are status names and values are status counts.", + "format": "int32" + }, + "description": "Map of status counts where keys are status names and values are status counts." + } + }, + "description": "Aggregated status response.", + "example": { + "taskName": "Task Name", + "statusCounts": { + "Completed": 3, + "In Pending": 2 + } + } + }, + "DetailsResponse": { + "type": "object", + "properties": { + "taskId": { + "type": "integer", + "description": "ID of the task.", + "format": "int32" + }, + "deviceId": { + "type": "integer", + "description": "ID of the device.", + "format": "int32" + }, + "deviceName": { + "type": "string", + "description": "Name of the device." + }, + "taskName": { + "type": "string", + "description": "Name of the task." + }, + "status": { + "type": "string", + "description": "Status of the task." + }, + "output": { + "type": "string", + "description": "Output of the task." + }, + "message": { + "type": "string", + "description": "Message of the task." + }, + "outputFileName": { + "type": "string", + "description": "Output file name." + } + }, + "description": "Details response for a task.", + "example": { + "taskId": 9712342, + "deviceId": 2071979267, + "deviceName": "Device 1", + "taskName": "Create log file", + "status": "Success", + "output": "Task did not produce any output.", + "message": "Successful execution on remote device." + } + }, + "ListResponseDetailsResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DetailsResponse" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "ListResponseOrganizationUnit": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationUnit" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "OrganizationUnit": { + "type": "object", + "properties": { + "orgUnitId": { + "type": "string", + "description": "The ID of the organization unit." + }, + "orgUnitName": { + "type": "string", + "description": "The name of the organization unit." + }, + "orgUnitType": { + "type": "string", + "description": "The type of the organization unit (SYSTEM, SO, CUSTOMER or SITE)." + }, + "parentId": { + "type": "string", + "description": "The ID of the parent organization unit." + }, + "externalId": { + "type": "string", + "description": "The external ID of the organization unit." + }, + "externalId2": { + "type": "string", + "description": "The external ID 2 of the organization unit." + }, + "contactFirstName": { + "type": "string", + "description": "First name of the contact for the organization unit." + }, + "contactLastName": { + "type": "string", + "description": "Last name of the contact for the organization unit." + }, + "phone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactTitle": { + "type": "string", + "description": "Title of the contact for the organization unit." + }, + "contactEmail": { + "type": "string", + "description": "Contact email for the organization unit." + }, + "contactPhone": { + "type": "string", + "description": "Telephone of the contact for the organization unit." + }, + "contactPhoneExt": { + "type": "string", + "description": "Telephone extension of the contact for the organization unit." + }, + "contactDepartment": { + "type": "string", + "description": "Department of the contact for the organization unit." + }, + "street1": { + "type": "string", + "description": "First line of street address for the organization unit." + }, + "street2": { + "type": "string", + "description": "Second line of street address for the organization unit." + }, + "city": { + "type": "string", + "description": "City where the organization unit is located." + }, + "stateProv": { + "type": "string", + "description": "State or province where the organization unit is located." + }, + "country": { + "type": "string", + "description": "Country where the organization unit is located. Must be two characters country code, see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2." + }, + "postalCode": { + "type": "string", + "description": "Postal code of the organization unit location." + }, + "generation": { + "type": "integer", + "description": "The generation (depth in the customer hierarchy) of the customer.", + "format": "int32" + }, + "descendantCount": { + "type": "integer", + "description": "The number of direct (immediate-children) descendants of the customer.", + "format": "int32" + } + }, + "description": "Data object for organization unit.", + "example": { + "orgUnitId": "100", + "orgUnitName": "N-able", + "orgUnitType": "CUSTOMER", + "parentId": "50", + "externalId": "extId", + "externalId2": "extId2", + "phone": "phone", + "contactTitle": "contact title", + "contactFirstName": "contact first name", + "contactLastName": "contact last name", + "contactEmail": "admin@n-able.com", + "contactPhone": "(123)456-7890", + "contactPhoneExt": null, + "contactDepartment": "Support", + "street1": "One Street", + "street2": "", + "city": "Ottawa", + "stateProv": "Ontario", + "country": "CA", + "county": null, + "postalCode": "A1A 1A1" + } + }, + "Links": { + "type": "object", + "properties": { + "firstPage": { + "type": "string" + }, + "previousPage": { + "type": "string" + }, + "nextPage": { + "type": "string" + }, + "lastPage": { + "type": "string" + } + } + }, + "QueryResponseUser": { + "required": [ + "_links" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/User" + } + }, + "pageNumber": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + }, + "itemCount": { + "type": "integer", + "format": "int32" + }, + "totalItems": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "_links": { + "$ref": "#/components/schemas/Links" + }, + "_warning": { + "type": "string" + } + } + }, + "User": { + "type": "object", + "properties": { + "firstName": { + "type": "string", + "description": "The first name of the user.", + "example": "John" + }, + "lastName": { + "type": "string", + "description": "The last name of the user.", + "example": "Doe" + }, + "apiOnlyUser": { + "type": "boolean", + "description": "Indicates if the user is API only.", + "example": false + }, + "description": { + "type": "string", + "description": "A description of the user.", + "example": "Test description" + }, + "isEnabled": { + "type": "boolean", + "description": "Indicates if the user is enabled.", + "example": true + }, + "isLdap": { + "type": "boolean", + "description": "Indicates if the user is managed through LDAP.", + "example": false + }, + "isLocked": { + "type": "boolean", + "description": "Indicates if the user's account is locked.", + "example": false + }, + "loggedInUser": { + "type": "boolean", + "description": "Indicates if the user is currently logged in.", + "example": false + }, + "readOnly": { + "type": "boolean", + "description": "Indicates if the user has read-only access.", + "example": false + }, + "supportUser": { + "type": "boolean", + "description": "Indicates if the user is a support user.", + "example": false + }, + "userId": { + "type": "integer", + "description": "The unique identifier of the user.", + "format": "int32", + "example": 1234567890 + }, + "userName": { + "type": "string", + "description": "The email address or username of the user.", + "example": "johndoe@example.com" + }, + "accessGroupIds": { + "type": "array", + "description": "A list of access group ids associated with the user.", + "items": { + "type": "integer", + "description": "A list of access group ids associated with the user.", + "format": "int32" + } + }, + "currentSsoProvider": { + "type": "string", + "description": "The current Single Sign-On provider for the user, if any.", + "example": "None" + }, + "customerTree": { + "type": "array", + "description": "The hierarchy of customer units associated with the user.", + "items": { + "type": "string", + "description": "The hierarchy of customer units associated with the user." + } + }, + "fullName": { + "type": "string", + "description": "The full name of the user.", + "example": "John Doe" + }, + "roleIds": { + "type": "array", + "description": "A list of role ids assigned to the user.", + "items": { + "type": "integer", + "description": "A list of role ids assigned to the user.", + "format": "int32" + } + }, + "twoFactorEnabled": { + "type": "boolean", + "description": "Indicates if two-factor authentication is enabled for the user.", + "example": false + } + }, + "description": "Represents the response for a user inside user list endpoint. It provides details about the user.", + "example": { + "firstName": "John", + "lastName": "Doe", + "apiOnlyUser": false, + "description": "Test description", + "isEnabled": true, + "isLdap": false, + "isLocked": false, + "loggedInUser": false, + "readOnly": false, + "supportUser": false, + "userId": 1234567890, + "userName": "johndoe@example.com", + "accessGroupIds": [ + 1, + 2, + 3 + ], + "currentSsoProvider": "None", + "customerTree": [ + "System", + "John's SO", + "Customer 1" + ], + "fullName": "John Doe", + "roleIds": [ + 12, + 13, + 14 + ], + "twoFactorEnabled": false + } + }, + "QueryResponseUserRole": { + "required": [ + "_links" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserRole" + } + }, + "pageNumber": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + }, + "itemCount": { + "type": "integer", + "format": "int32" + }, + "totalItems": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "_links": { + "$ref": "#/components/schemas/Links" + }, + "_warning": { + "type": "string" + } + } + }, + "UserRole": { + "type": "object", + "properties": { + "roleId": { + "type": "integer", + "description": "The user role id.", + "format": "int32" + }, + "roleName": { + "type": "string", + "description": "The user role name." + }, + "roleDescription": { + "type": "string", + "description": "The description of a user role." + }, + "_extra": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The extra information." + }, + "description": "The extra information." + } + }, + "description": "Represents the response for a user role. It provides details about the role id, role name and description,\n as well as extra information.\n", + "example": { + "roleId": 1001, + "roleName": "Default Dashboard Role", + "roleDescription": "Grants users read-only access to Dashboards, and the ability to view service details.", + "_extra": { + "cloneable": true, + "readonly": true, + "usernames": [ + "User 1 One", + "User Server Room", + "User 2 Two" + ], + "permissions": [ + "DASHBOARDS_VIEW", + "SERVICE_VIEW" + ] + } + } + }, + "UserRoleDetails": { + "type": "object", + "properties": { + "roleId": { + "type": "integer", + "description": "The user role id.", + "format": "int32" + }, + "orgUnitId": { + "type": "integer", + "description": "The organization unit id where the role is defined.", + "format": "int32" + }, + "roleName": { + "type": "string", + "description": "The user role name." + }, + "roleDescription": { + "type": "string", + "description": "The description of a user role." + }, + "userIds": { + "type": "array", + "description": "The user ids assigned to role.", + "items": { + "type": "integer", + "description": "The user ids assigned to role.", + "format": "int32" + } + }, + "_extra": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "Extra information." + }, + "description": "Extra information." + } + }, + "description": "Represents the response for a user role. It provides details about the role id, role name and description,\n as well as extra information.\n", + "example": { + "roleId": 1001, + "orgUnitId": 1, + "roleName": "Default Dashboard Role", + "roleDescription": "Grants users read-only access to Dashboards, and the ability to view service details.", + "userIds": [ + 111333683, + 444512252, + 1210074793 + ], + "_extra": { + "cloneable": true, + "readonly": true, + "permissions": [ + "DASHBOARDS_VIEW", + "SERVICE_VIEW" + ] + } + } + }, + "UserRoleDetailsResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserRoleDetails" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + } + }, + "DefaultCustomProperty": { + "type": "object", + "properties": { + "propertyId": { + "type": "integer", + "description": "The property id.", + "format": "int32" + }, + "propertyName": { + "type": "string", + "description": "The property name." + }, + "orgUnitId": { + "type": "integer", + "description": "The ID of the 'Home' organization unit at which the custom property was created.", + "format": "int32" + }, + "level": { + "type": "string", + "description": "The property level (ORGANIZATION_UNIT/DEVICE).", + "enum": [ + "DEVICE", + "ORGANIZATION_UNIT", + "ORGANIZATION_UNIT", + "DEVICE" + ] + }, + "propertyType": { + "type": "string", + "description": "The property type.", + "enum": [ + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD", + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD" + ] + }, + "propagationType": { + "type": "string", + "description": "The way how the property value changes are propagated down the organization unit hierarchy.", + "enum": [ + "NO_PROPAGATION", + "SERVICE_ORGANIZATION_ONLY", + "SERVICE_ORGANIZATION_AND_CUSTOMER_AND_SITE", + "SERVICE_ORGANIZATION_AND_CUSTOMER", + "SERVICE_ORGANIZATION_AND_SITE", + "CUSTOMER_AND_SITE", + "CUSTOMER_ONLY", + "SITE_ONLY", + "NO_PROPAGATION", + "SERVICE_ORGANIZATION_ONLY", + "SERVICE_AND_ORGANIZATION", + "SERVICE_AND_ORGANIZATION_AND_DEVICE", + "SERVICE_AND_DEVICE", + "ORGANIZATION_AND_DEVICE", + "ORGANIZATION_ONLY", + "DEVICE_ONLY" + ] + }, + "defaultValue": { + "type": "string", + "description": "The default value of the property." + }, + "selectedOrgUnitIds": { + "type": "array", + "description": "The entire list of organization unit IDs to which the custom property is applicable. The list includes the 'Home' organization unit and all its child organization units.", + "items": { + "type": "integer", + "description": "The entire list of organization unit IDs to which the custom property is applicable. The list includes the 'Home' organization unit and all its child organization units.", + "format": "int32" + } + }, + "enumeratedValueList": { + "type": "array", + "description": "The list of allowed values for the property, if the property type is ENUMERATED.", + "items": { + "type": "string", + "description": "The list of allowed values for the property, if the property type is ENUMERATED." + } + } + }, + "description": "The default custom property (DEVICE/ORGANIZATION_UNIT).", + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "orgUnitId": 11090, + "level": "ORGANIZATION_UNIT", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE", + "selectedOrgUnitIds": [ + 11089, + 11090 + ] + } + }, + "GetCustomerLimitsResponse": { + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CustomerLimitResponseEntity" + } + } + }, + "description": "Response for getting customer limits", + "example": { + "message": "Customer limits retrieved successfully.", + "data": [ + { + "limitName": "MaxUsers", + "value": "100", + "maxValue": "200" + }, + { + "limitName": "MaxDevices", + "value": "500", + "maxValue": "1000" + } + ] + } + }, + "ListResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "Device": { + "type": "object", + "properties": { + "deviceId": { + "type": "integer", + "format": "int32" + }, + "uri": { + "type": "string" + }, + "remoteControlUri": { + "type": "string" + }, + "sourceUri": { + "type": "string" + }, + "longName": { + "type": "string" + }, + "deviceClass": { + "type": "string" + }, + "description": { + "type": "string" + }, + "isProbe": { + "type": "boolean" + }, + "osId": { + "type": "string" + }, + "supportedOs": { + "type": "string" + }, + "discoveredName": { + "type": "string" + }, + "deviceClassLabel": { + "type": "string" + }, + "supportedOsLabel": { + "type": "string" + }, + "lastLoggedInUser": { + "type": "string" + }, + "stillLoggedIn": { + "type": "string" + }, + "licenseMode": { + "type": "string" + }, + "orgUnitId": { + "type": "integer", + "format": "int32" + }, + "soId": { + "type": "integer", + "format": "int32" + }, + "soName": { + "type": "string" + }, + "customerId": { + "type": "integer", + "format": "int32" + }, + "customerName": { + "type": "string" + }, + "siteId": { + "type": "integer", + "format": "int32" + }, + "siteName": { + "type": "string" + }, + "applianceId": { + "type": "integer", + "format": "int32" + }, + "lastApplianceCheckinTime": { + "type": "string", + "description": "Last reported check in time of the agent", + "format": "date-time", + "example": "2017-02-16T21:00:00+01:00" + }, + "lastApplianceCheckinTimeLocal": { + "type": "string", + "description": "Last reported check in time of the agent in server local time with timezone offset", + "format": "date-time", + "example": "2017-02-16T21:00:00+01:00" + }, + "deviceStatus": { + "$ref": "#/components/schemas/DeviceStatus" + } + }, + "description": "Response for list of devices.", + "example": { + "deviceId": 1299930810, + "uri": "52.141.77.215", + "remoteControlUri": "", + "sourceUri": "", + "longName": "WS_01-12091-001001", + "deviceClass": "Workstations - Windows", + "description": "Network device discovered using Asset Discovery - 1299930810", + "isProbe": false, + "osId": "winnt", + "supportedOs": "Microsoft Windows 7 Ultimate x64 Edition", + "discoveredName": "WS_01-12091-001001", + "deviceClassLabel": "Workstations - Windows", + "supportedOsLabel": "Microsoft Windows 7 Ultimate x64 Edition", + "lastLoggedInUser": "-", + "stillLoggedIn": "", + "licenseMode": "Professional", + "orgUnitId": 12091, + "soId": 12091, + "soName": "Service_Organization", + "customerId": 12091, + "customerName": "PERF_ALL_DEVICES_CUST_01", + "siteId": 12091, + "siteName": "PERF_ALL_DEVICES_SITE_0001", + "lastApplianceCheckinTime": "2017-02-16T21:00:00.000+01:00", + "lastApplianceCheckinTimeLocal": "2017-02-16T21:00:00.000+01:00", + "applianceId": 12091 + } + }, + "DeviceStatus": { + "type": "object", + "properties": { + "state": { + "type": "integer", + "description": "The state of the device.", + "format": "int32" + }, + "status": { + "type": "integer", + "description": "The status of the device.", + "format": "int32" + } + }, + "description": "The aggregate status of the device." + }, + "QueryResponseDevice": { + "required": [ + "_links" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Device" + } + }, + "pageNumber": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + }, + "itemCount": { + "type": "integer", + "format": "int32" + }, + "totalItems": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "_links": { + "$ref": "#/components/schemas/Links" + }, + "_warning": { + "type": "string" + } + } + }, + "ListResponseOrganizationCustomProperty": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationCustomProperty" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "OrganizationCustomProperty": { + "type": "object", + "properties": { + "propertyId": { + "type": "integer", + "description": "The property id.", + "format": "int32", + "readOnly": true + }, + "propertyName": { + "type": "string", + "description": "The property name.", + "readOnly": true + }, + "propertyType": { + "type": "string", + "description": "The property type.", + "readOnly": true, + "enum": [ + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD", + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD" + ] + }, + "value": { + "type": "string", + "description": "The property value." + }, + "enumeratedValueList": { + "type": "array", + "description": "The possible values of the property.", + "readOnly": true, + "items": { + "type": "string", + "description": "The possible values of the property.", + "readOnly": true + } + } + }, + "description": "The custom property (DEVICE/ORGANIZATION_UNIT).", + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE" + } + }, + "DefaultDeviceCustomProperty": { + "type": "object", + "properties": { + "propertyId": { + "type": "integer", + "format": "int32" + }, + "customerId": { + "type": "integer", + "format": "int32" + }, + "propertyName": { + "type": "string" + }, + "propertyLevel": { + "type": "string" + }, + "propertyType": { + "type": "string", + "enum": [ + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD" + ] + }, + "value": { + "type": "string" + }, + "enumeratedValues": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeviceCustomPropertyEnumeratedValue" + } + }, + "deviceClasses": { + "type": "array", + "items": { + "type": "string" + } + }, + "supportedOs": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "description": "Response for default custom property.", + "example": " {\n \"propertyId\": 1815170007,\n \"customerId\": 100,\n \"propertyName\": \"customer1-NCC-4407-dateProperty1\",\n \"propertyLevel\": \"DEVICE\",\n \"propertyType\": \"DATE\",\n \"defaultValue\": \"1707886800000\",\n \"deviceClasses\": [\n \"Laptop - Windows\",\n ],\n \"supportedOs\": [\n \"Windows 10\",\n \"Windows 7\",\n ]\n }\n" + }, + "DeviceCustomPropertyEnumeratedValue": { + "type": "object", + "properties": { + "customerId": { + "type": "integer", + "format": "int32" + }, + "customerName": { + "type": "string" + }, + "customerType": { + "type": "integer", + "format": "int32" + }, + "propertyId": { + "type": "integer", + "format": "int32" + }, + "propertyValue": { + "type": "string" + } + } + }, + "DeviceCustomPropertyResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/DefaultDeviceCustomProperty" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Response for device custom property information.", + "example": " {\n data: {\n \"propertyId\": 1815170007,\n \"customerId\": 100,\n \"propertyName\": \"customer1-NCC-4407-dateProperty1\",\n \"propertyLevel\": \"DEVICE\",\n \"propertyType\": \"DATE\",\n \"defaultValue\": \"1707886800000\",\n \"deviceClasses\": [\n \"Laptop - Windows\",\n ],\n \"supportedOs\": [\n \"Windows 10\",\n \"Windows 7\"\n ]\n }\n }\n" + }, + "ActiveIssue": { + "type": "object", + "properties": { + "orgUnitId": { + "type": "integer", + "description": "The organization unit id.", + "format": "int32", + "example": 100 + }, + "deviceId": { + "type": "integer", + "description": "The device id.", + "format": "int32", + "example": 576589254 + }, + "notificationState": { + "type": "integer", + "description": "The notification state.", + "format": "int32", + "example": 1 + }, + "serviceId": { + "type": "integer", + "description": "The service id.", + "format": "int32", + "example": 496 + }, + "serviceName": { + "type": "string", + "description": "The service name.", + "example": "Windows UAC Status" + }, + "serviceType": { + "type": "string", + "description": "The service type.", + "example": "AMP" + }, + "taskId": { + "type": "integer", + "description": "The task id.", + "format": "int32", + "example": 2096172314 + }, + "serviceItemId": { + "type": "integer", + "description": "The service item id.", + "format": "int32", + "example": 36893 + }, + "_extra": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "The _extra information.", + "example": " {\n \"soCustomerID\": 50,\n \"deviceName\": \"NCC-9992\",\n ...\n }\n" + }, + "description": "The _extra information.", + "example": " {\n \"soCustomerID\": 50,\n \"deviceName\": \"NCC-9992\",\n ...\n }\n" + } + }, + "description": "Represents a response containing an active issue.", + "example": { + "orgUnitId": 102, + "deviceId": 576589254, + "notificationState": 5, + "serviceId": 496, + "serviceName": "Windows UAC Status", + "serviceType": "AMP", + "taskId": 2096172314, + "serviceItemId": 36893, + "_extra": { + "numberOfAcknowledgedNotification": null, + "avdUpdateServerEnabled": false, + "licenseMode": "Professional", + "psaIntegrationDisabled": false, + "avdProtectionEnabled": true, + "remoteControllable": true, + "reactiveSupported": true, + "partOfNotification": false, + "remoteControlState": "disconnected", + "acknowledgedBy": "", + "avdVersion": "", + "deviceName": "NCC-9996", + "ticketCreationInProgress": null, + "transitionTime": "2024-04-02T16:15:33.432Z", + "integrationStatuses": [], + "lwtEdrStatus": "", + "patchManagementEnabled": false, + "backupManagerProfile": "", + "mspBackupProfile": "", + "securityManagerProfile": "", + "notificationAcknowledgmentInProgress": false, + "taskIdent": "", + "microsoftPatchManagementEnabled": false, + "deviceClassValue": null, + "backupManagerVersion": "", + "securityManagerVersion": "", + "remoteControlConnected": null, + "monitoringDisabled": false, + "numberOfActiveNotification": 0, + "psaIntegrationExists": false, + "lwtEdrEnabled": false, + "mspBackupVersion": "", + "thirdPartyPatchManagementEnabled": false, + "probe": false, + "reactiveEnabled": true, + "netPathEnabled": false, + "deviceClassLabel": null, + "mspBackupEnabled": false, + "port": "", + "diskEncryptionEnabled": false, + "customerTree": [ + "System", + "Service_Organization", + "Customer 2" + ], + "securityManagerEnabled": false, + "psaTicketDetails": "", + "soCustomerID": 50, + "maintenanceWindowEnabled": false, + "backupManagerEnabled": false, + "patchManagementProfile": "" + } + } + }, + "QueryResponseActiveIssue": { + "required": [ + "_links" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ActiveIssue" + } + }, + "pageNumber": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + }, + "itemCount": { + "type": "integer", + "format": "int32" + }, + "totalItems": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "_links": { + "$ref": "#/components/schemas/Links" + }, + "_warning": { + "type": "string" + } + } + }, + "QueryResponse": { + "required": [ + "_links" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "object" + } + }, + "pageNumber": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + }, + "itemCount": { + "type": "integer", + "format": "int32" + }, + "totalItems": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "_links": { + "$ref": "#/components/schemas/Links" + }, + "_warning": { + "type": "string" + } + } + }, + "Health": { + "type": "object", + "properties": { + "currentTime": { + "type": "string", + "format": "date-time" + } + }, + "description": "Response for the server health.", + "example": { + "currentTime": "2023-09-27T15:43:16.793Z" + } + }, + "DeviceResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/Device" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + } + }, + "DeviceServiceMonitoringStatus": { + "type": "object", + "properties": { + "taskId": { + "type": "integer", + "format": "int32" + }, + "serviceId": { + "type": "integer", + "format": "int32" + }, + "timeToStale": { + "type": "integer", + "format": "int32" + }, + "taskNote": { + "type": "string" + }, + "taskIdent": { + "type": "string" + }, + "stateStatus": { + "type": "string" + }, + "lastUpdate": { + "type": "string" + }, + "lastDataId": { + "type": "integer", + "format": "int32" + }, + "createdOn": { + "type": "string" + }, + "moduleName": { + "type": "string" + }, + "serviceItemId": { + "type": "integer", + "format": "int32" + }, + "lastScanTime": { + "type": "string" + }, + "isManagedTask": { + "type": "boolean" + }, + "transitionTime": { + "type": "string" + }, + "applianceId": { + "type": "integer", + "format": "int32" + }, + "applianceName": { + "type": "string" + } + }, + "description": "Response for Device Service Monitoring Status information.", + "example": [ + { + "taskId": 27446324, + "serviceId": 496, + "timeToStale": 195, + "taskNote": "Added by service template [ Workstations - Windows ]", + "taskIdent": "", + "stateStatus": "Disconnected", + "lastUpdate": null, + "lastDataId": null, + "createdOn": null, + "moduleName": "Windows UAC Status", + "serviceItemId": 31109, + "lastScanTime": "2024-02-28 15:25:05.939 -0500", + "isManagedTask": true, + "transitionTime": "2024-02-28 15:40:42.407" + }, + { + "taskId": 27446329, + "serviceId": 486, + "timeToStale": 105, + "taskNote": "Added by service template [ Workstations - Windows ]", + "taskIdent": "", + "stateStatus": "Connected", + "lastUpdate": null, + "lastDataId": null, + "createdOn": null, + "moduleName": "Windows UAC Status", + "serviceItemId": 31119, + "lastScanTime": "2024-02-28 15:25:05.939 -0500", + "isManagedTask": true, + "transitionTime": "2024-02-28 15:40:42.407" + } + ] + }, + "ListResponseDeviceServiceMonitoringStatus": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeviceServiceMonitoringStatus" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "ListResponseTaskStatusResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskStatusResponse" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "TaskStatusResponse": { + "type": "object", + "properties": { + "taskId": { + "type": "integer", + "format": "int32" + }, + "taskName": { + "type": "string" + }, + "status": { + "type": "string" + } + } + }, + "DeviceRemoteControlInfo": { + "type": "object", + "properties": { + "deviceId": { + "type": "integer", + "description": "Echoes the requested device id.", + "format": "int32", + "example": 12345 + }, + "remoteControllable": { + "type": "boolean", + "description": "Whether remote control is enabled / available for this device." + }, + "remoteControlType": { + "type": "string", + "description": "Effective RC type resolved from device override or class default map.", + "enum": [ + "MSP_ANYWHERE", + "RDP", + "WEB", + "SSH", + "TELNET", + "GENERIC", + "NONE" + ] + }, + "remoteControlState": { + "type": "string", + "description": "Current state.", + "enum": [ + "CONNECTED", + "DISCONNECTED", + "AVAILABLE_WITH_WARNING", + "NOT_AVAILABLE_DEFAULT_TYPE", + "NOT_AVAILABLE" + ] + } + }, + "description": "Remote-control configuration for a single device." + }, + "DeviceRemoteControlInfoResponse": { + "type": "object", + "properties": { + "status": { + "type": "integer", + "description": "The HTTP status code.", + "format": "int32", + "example": 200 + }, + "message": { + "type": "string", + "description": "A human-readable message describing the result.", + "example": "Remote Control state fetched successfully." + }, + "data": { + "$ref": "#/components/schemas/DeviceRemoteControlInfo" + } + }, + "description": "Wrapper response for the device remote-control configuration.", + "example": { + "status": 200, + "message": "Remote Control state fetched successfully.", + "data": { + "deviceId": 12345, + "remoteControllable": true, + "remoteControlType": "MSP_ANYWHERE", + "remoteControlState": "CONNECTED" + } + } + }, + "DeviceNoteItem": { + "type": "object", + "properties": { + "deviceNoteId": { + "type": "integer", + "description": "The unique ID of the device note", + "format": "int32", + "example": 101 + }, + "deviceId": { + "type": "integer", + "description": "The ID of the device this note belongs to", + "format": "int32", + "example": 12345 + }, + "userId": { + "type": "integer", + "description": "The ID of the user who created the note", + "format": "int32", + "example": 50 + }, + "note": { + "type": "string", + "description": "The content of the note", + "example": "Device maintenance completed" + }, + "email": { + "type": "string", + "description": "The email of the user who created the note", + "example": "user@example.com" + }, + "lastUpdated": { + "type": "string", + "description": "The timestamp when the note was created or updated", + "example": "2024-01-15T10:30:00Z" + } + }, + "description": "A device note" + }, + "QueryResponseDeviceNoteItem": { + "required": [ + "_links" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeviceNoteItem" + } + }, + "pageNumber": { + "type": "integer", + "format": "int32" + }, + "pageSize": { + "type": "integer", + "format": "int32" + }, + "itemCount": { + "type": "integer", + "format": "int32" + }, + "totalItems": { + "type": "integer", + "format": "int32" + }, + "totalPages": { + "type": "integer", + "format": "int32" + }, + "_links": { + "$ref": "#/components/schemas/Links" + }, + "_warning": { + "type": "string" + } + } + }, + "ListResponseMaintenanceWindowGetResponse": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MaintenanceWindowGetResponse" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "MaintenanceWindowGetResponse": { + "type": "object", + "properties": { + "scheduleID": { + "type": "integer", + "format": "int32" + }, + "userName": { + "type": "string" + }, + "lastUpdated": { + "type": "string" + }, + "applicableAction": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApplicableAction" + } + }, + "name": { + "type": "string" + }, + "type": { + "type": "string" + }, + "cron": { + "type": "string" + }, + "duration": { + "type": "integer", + "format": "int32" + }, + "enabled": { + "type": "boolean" + }, + "maxDowntime": { + "type": "integer", + "format": "int32" + }, + "rebootMethod": { + "type": "string" + }, + "rebootDelay": { + "type": "integer", + "format": "int32" + }, + "downtimeOnAction": { + "type": "boolean" + }, + "userMessageEnabled": { + "type": "boolean" + }, + "userMessage": { + "type": "string" + }, + "messageSenderEnabled": { + "type": "boolean" + }, + "messageSender": { + "type": "string" + }, + "preserveStateEnabled": { + "type": "boolean" + }, + "ruleID": { + "type": "integer", + "format": "int32" + }, + "ruleName": { + "type": "string" + } + }, + "description": "Response for list of Maintenance Windows.", + "example": { + "scheduleID": 123456789, + "userName": "admin", + "lastUpdated": "2021-09-01T00:00:00Z", + "applicableAction": [ + { + "type": "Patch", + "actions": [ + { + "Key": "reboot", + "Value": null + } + ] + } + ], + "name": "Test Maintenance Window", + "type": "action", + "cron": "0 0 0 ? 2 1,4 *", + "duration": 60, + "enabled": "true", + "maxDowntime": "0", + "rebootMethod": "", + "rebootDelay": 0, + "downTimeOnAction": false, + "userMessageEnabled": false, + "userMessage": null, + "messageSenderEnabled": false, + "messageSender": null, + "preserveStateEnabled": false, + "ruleID": 123456789, + "ruleName": "Test Rule" + } + }, + "DeviceCustomProperty": { + "type": "object", + "properties": { + "propertyId": { + "type": "integer", + "description": "The property id.", + "format": "int32", + "readOnly": true + }, + "propertyName": { + "type": "string", + "description": "The property name.", + "readOnly": true + }, + "propertyType": { + "type": "string", + "description": "The property type.", + "readOnly": true, + "enum": [ + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD", + "HTML_LINK", + "TEXT", + "DATE", + "ENUMERATED", + "PASSWORD" + ] + }, + "value": { + "type": "string", + "description": "The property value." + }, + "enumeratedValueList": { + "type": "array", + "description": "The possible value of the property.", + "readOnly": true, + "items": { + "type": "string", + "description": "The possible value of the property.", + "readOnly": true + } + } + }, + "description": "The custom property (DEVICE/ORGANIZATION_UNIT).", + "example": { + "propertyId": 1624300373, + "propertyName": "ORG_01-0620", + "propertyType": "TEXT", + "value": "ORG_01-0620 VALUE" + } + }, + "ListResponseDeviceCustomProperty": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeviceCustomProperty" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "DeviceAssetInfoResponse": { + "type": "object", + "properties": { + "data": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "Asset Information about the device." + }, + "description": "Asset Information about the device." + }, + "description": "Asset Information about the device." + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + }, + "description": "Represents a device asset info response.\nIt contains the asset information about the device in the form of following categories :\n1. os\n2. application\n3. computersystem\n4. networkadapter\n5. device\n6. processor\n\nThe above categories are classified as \"default\" categories and the fields under these categories are considered\n as \"default\" fields.\n\nThe default fields are considered definitive and are expected to be present at all times.\nIf a default field is missing,\n it indicates that information about that specific field for the device is unavailable.\n\nThe \"_extra\" part of the response contains all available asset categories and fields.\n\nThe extra categories and fields provide supplementary information about the device asset.\nThese details are optional and may or may not be available in the future.\nAdditionally, certain fields from the \"_extra\" categories or fields might transition to become default categories\nor fields in the future.\n", + "example": { + "os": { + "reportedos": "Microsoft Windows 10 Enterprise", + "osarchitecture": "64-bit", + "version": "10.0.19045" + }, + "application": { + "list": [ + { + "_index": 0, + "displayname": "Microsoft Visual C++ 2022 X64 Additional Runtime - 14.36.32532" + } + ] + }, + "computersystem": { + "serialnumber": "None", + "netbiosname": "NCC-0625", + "model": "VMware7,1", + "totalphysicalmemory": "2147483648", + "manufacturer": "VMware, Inc." + }, + "networkadapter": { + "list": [ + { + "ipaddress": "10.120.207.82", + "_index": 0, + "dnsserver": "10.120.0.10, 10.220.0.10, 10.100.0.10", + "description": "vmxnet3 Ethernet Adapter", + "dhcpserver": null, + "macaddress": "00:50:56:87:23:5f", + "gateway": "10.120.207.1" + } + ] + }, + "device": { + "longname": "NCC-0625", + "deleted": "false", + "lastlogin": "2024-01-11 12:07:47.908 -0500", + "deviceclass": "Workstations - Windows", + "deviceid": "1065910111", + "uri": "10.120.207.82" + }, + "processor": { + "name": "Intel(R) Xeon(R) Gold 6252 CPU @ 2.10GHz", + "numberofcores": "1", + "numberofcpus": "1" + }, + "_extra": { + "osfeatures": { + "list": [ + { + "_index": 0, + "pvalue": "5.1.19041.1", + "pkey": "PowerShellVersion" + }, + { + "_index": 1, + "pvalue": "Microsoft.PowerShell.Diagnostics", + "pkey": "PowerShell-SnapIn-0" + } + ] + }, + "motherboard": { + "product": "440BX Desktop Reference Platform", + "serialnumber": "None", + "biosversion": "VMW71.00V.21100432.B64.2301110304", + "version": "None", + "manufacturer": "Intel Corporation" + } + } + } + }, + "AssetLifecycleDetails": { + "type": "object", + "properties": { + "warrantyExpiryDate": { + "type": "string" + }, + "leaseExpiryDate": { + "type": "string" + }, + "expectedReplacementDate": { + "type": "string" + }, + "purchaseDate": { + "type": "string" + }, + "cost": { + "type": "number" + }, + "location": { + "type": "string" + }, + "assetTag": { + "type": "string" + }, + "description": { + "type": "string" + }, + "updateWarrantyError": { + "type": "string" + }, + "lastSystemWarrantyDiscovery": { + "type": "string" + }, + "lastDiscovery": { + "type": "string" + } + }, + "description": "Asset Lifecycle details", + "example": { + "warrantyExpiryDate": "2022-12-31", + "leaseExpiryDate": "2022-12-31", + "expectedReplacementDate": "2022-12-31", + "purchaseDate": "2022-12-31", + "cost": 0.0, + "location": "location", + "assetTag": "assetTag", + "description": "description", + "updateWarrantyError": "updateWarrantyError", + "lastSystemWarrantyDiscovery": "2024-07-31T06:18:00Z", + "lastDiscovery": "2024-08-06T06:25:00Z" + } + }, + "DeviceActivationKeyResponse": { + "type": "object", + "properties": { + "activationKey": { + "type": "string", + "description": "The generated activation key for the device." + }, + "expirationDate": { + "type": "string", + "description": "The expiration date of the activation key in ISO 8601 format." + } + }, + "description": "Response for generating a device activation key.", + "example": { + "activationKey": "1234567890abcdef=", + "expirationDate": "2024-12-31T23:59:59Z" + } + }, + "Filter": { + "type": "object", + "properties": { + "filterId": { + "type": "string" + }, + "filterName": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "description": "Response for list of device filters.", + "example": { + "filterId": 75, + "filterName": "Laptops - Windows", + "description": "Laptop devices running Windows." + } + }, + "ListResponseFilter": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Filter" + } + }, + "totalItems": { + "type": "integer", + "format": "int32" + } + } + }, + "InstallerSoftware": { + "type": "object", + "properties": { + "softwareId": { + "type": "integer", + "format": "int32" + }, + "softwareName": { + "type": "string" + }, + "description": { + "type": "string" + }, + "installerType": { + "type": "string" + }, + "operatingSystem": { + "type": "string" + }, + "softwareType": { + "type": "string" + }, + "version": { + "type": "string" + } + }, + "description": "Details of installer software.", + "example": { + "softwareId": 123, + "softwareName": "Example Software", + "description": "This is an example software installer.", + "installerType": "MSI", + "operatingSystem": "Windows", + "softwareType": "Agent", + "version": "1.0.0" + } + }, + "ApplianceTaskInformation": { + "type": "object", + "properties": { + "scanTime": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "NO_STATE", + "NO_DATA", + "STALE", + "NORMAL", + "WARNING", + "FAILED", + "MISCONFIGURED", + "DISCONNECTED", + "DISABLED" + ] + }, + "errorMessage": { + "type": "string" + }, + "serviceDetails": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApplianceTaskStatusDetail" + } + } + }, + "description": "The appliance task information", + "example": { + "scanTime": "2024-05-23 11:28:09.55", + "state": "NORMAL", + "errorMessage": "", + "serviceDetails": [ + { + "scanDetailId": 3262200, + "detailName": "agent_chkinintvl", + "description": "Agent check-in interval (sec)", + "detailValue": "32", + "state": "NORMAL", + "monitoringType": "Normal", + "thresholds": [ + { + "state": "NORMAL", + "lowValue": 0, + "highValue": 300 + }, + { + "state": "WARNING", + "lowValue": 300, + "highValue": 600 + }, + { + "state": "FAILED", + "lowValue": 600, + "highValue": 4294967295 + } + ] + } + ] + } + }, + "ApplianceTaskStatusDetail": { + "type": "object", + "properties": { + "scanDetailId": { + "type": "integer", + "format": "int32" + }, + "detailName": { + "type": "string" + }, + "description": { + "type": "string" + }, + "detailValue": { + "type": "string" + }, + "state": { + "type": "string", + "enum": [ + "NO_STATE", + "NO_DATA", + "STALE", + "NORMAL", + "WARNING", + "FAILED", + "MISCONFIGURED", + "DISCONNECTED", + "DISABLED" + ] + }, + "monitoringType": { + "type": "string" + }, + "thresholds": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ApplianceTaskThresholdBasic" + } + } + } + }, + "ApplianceTaskThresholdBasic": { + "type": "object", + "properties": { + "state": { + "type": "string", + "enum": [ + "NO_STATE", + "NO_DATA", + "STALE", + "NORMAL", + "WARNING", + "FAILED", + "MISCONFIGURED", + "DISCONNECTED", + "DISABLED" + ] + }, + "lowValue": { + "type": "integer" + }, + "highValue": { + "type": "integer" + } + } + }, + "AccessGroupDetails": { + "type": "object", + "properties": { + "groupId": { + "type": "integer", + "description": "The id of the access group.", + "format": "int32" + }, + "orgUnitId": { + "type": "integer", + "description": "The id of the organizational unit where the access group is created.", + "format": "int32" + }, + "groupName": { + "type": "string", + "description": "The name of the access group." + }, + "groupDescription": { + "type": "string", + "description": "The description of the access group." + }, + "orgUnitIds": { + "type": "array", + "description": "List of organizational unit ids where this access group is applied. It is populated when the group type is by organization unit.", + "items": { + "type": "integer", + "description": "List of organizational unit ids where this access group is applied. It is populated when the group type is by organization unit.", + "format": "int32" + } + }, + "deviceIds": { + "type": "array", + "description": "List of device ids associated with the access group. It is populated when the group type is by device.", + "items": { + "type": "integer", + "description": "List of device ids associated with the access group. It is populated when the group type is by device.", + "format": "int32" + } + }, + "userIds": { + "type": "array", + "description": "List of user ids associated with the access group.", + "items": { + "type": "integer", + "description": "List of user ids associated with the access group.", + "format": "int32" + } + }, + "autoIncludeNewOrgUnits": { + "type": "boolean", + "description": "Indicates whether new organization units will be automatically associated to the access group." + }, + "_extra": { + "type": "object", + "additionalProperties": { + "type": "object", + "description": "Contains all the details about the access group under the '_extra' field." + }, + "description": "Contains all the details about the access group under the '_extra' field." + } + }, + "description": "Represents the response for fetching details of a specific access group.\nContains information about the access group, including its name, type, associated devices and users,\ndescription. Properties such as whether it's read-only or cloneable, are encapsulated under the \"_extra\" field.\n", + "example": { + "groupId": 1549311915, + "orgUnitId": 1, + "groupName": "group name", + "groupDescription": "description", + "orgUnitIds": [ + 1, + 50, + 102, + 100, + 101, + 103 + ], + "deviceIds": [], + "userIds": [], + "autoIncludeNewOrgUnits": false, + "_extra": { + "accessgroupapplication": null, + "grouptype": "ORG_UNIT", + "readonly": "false", + "customerid": "1", + "customers": "[1, 50, 102, 100, 101, 103]", + "cloneable": null, + "users": "[]" + } + } + }, + "AccessGroupGetResponse": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/AccessGroupDetails" + }, + "_links": { + "type": "object", + "additionalProperties": { + "type": "string", + "description": "Links to related endpoints." + }, + "description": "Links to related endpoints." + } + } + }, + "DeleteBatchNoteRequest": { + "required": [ + "noteIds" + ], + "type": "object", + "properties": { + "noteIds": { + "type": "array", + "description": "List of note IDs to delete.", + "example": [ + 10, + 20, + 30 + ], + "items": { + "type": "integer", + "description": "List of note IDs to delete.", + "format": "int32" + } + } + }, + "description": "Request body for deleting multiple notes from a device" + }, + "MaintenanceWindowsDeleteRequest": { + "required": [ + "scheduleIds" + ], + "type": "object", + "properties": { + "scheduleIds": { + "type": "array", + "description": "Schedule Ids for windows which are to be deleted", + "items": { + "type": "integer", + "description": "Schedule Ids for windows which are to be deleted", + "format": "int32" + } + } + }, + "description": "Represents a request to delete Maintenance Windows.", + "example": { + "scheduleIds": [ + 123456789, + 987654321, + 250124567 + ] + } + } + }, + "securitySchemes": { + "API-Access_Token": { + "type": "http", + "description": "Access token for API. You can get the token by authenticating. See \"POST - /api/auth/authenticate\".", + "scheme": "bearer", + "bearerFormat": "JWT" + }, + "N-central_User-API_Token_JWT": { + "type": "http", + "description": "N-central User-API Token (JWT). You can get this token from the N-central UI.", + "scheme": "bearer", + "bearerFormat": "JWT" + }, + "SSO_Access_Token": { + "type": "http", + "description": "SSO access token from an external identity provider (IdP). Use this to authenticate via SSO. See \"POST - /api/auth/sso\".", + "scheme": "bearer", + "bearerFormat": "JWT" + } + } + } +} \ No newline at end of file