Skip to main content

RESTful API

  • Updated

Introduction

OC Reporter comes with its own RESTful API. It can be used to list, modify, create, and remove data through HTTP(s) requests. Currently, not all possibilities available in the GUI are available in the API, but we are extending the API regularly. If you are missing an API endpoint, please contact our Support Team.

Anatomy of an API endpoint

Each API endpoint is structured in the following way:

<url-oc-reporter>/api/workspace/<ws-id>/<action>?_format=json&_token=<token>&_tenant=<ocid>&_language=en

where

  • <url-oc-reporter> is the main part of your OC Reporter URL, for example, https://ocreporter.company.com. If you are using the OC Reporter in the Octopus Cloud, then the OC Reporter URL is: https://splareporter2.octopus.cloud
  • <ws-id> is the unique ID of the workspace you are using in OC Reporter. To find out the workspace ID, go to your OC Reporter web application and click on the left sidebar under the dropdown WORKSPACE the small link Show workspace details. Copy from Workspace ID field the ID of the workspace.
  • <action> is the action you want to execute, for instance listing all virtual machines.
  • <token> is your unique API token. In OC Reporter Cloud-based web application, select your name on the top right corner. Click from the list the item My Account and after click My Organisation on the left menu. Copy from the API token field the token. If you are using the OC Reporter on-premises web application, simply open the octopus.json file saved in the installation folder of OC Reporter and copy the token from app.tenant_access_token.
  • <ocid> is your unique OCID. Select your name on the top right corner. Click from the list the item My Account and after click My Organisation on the left menu. Copy from the OCID field your OCID value.

Endpoints

The API can deliver the response in JSON or XML format. By default, JSON is used. If you prefer the XML format, you can modify the _format section of the API endpoint to xml instead of json (_format=xml) to get the response in XML format.

If an API endpoint request was successful, you will get a 200 OK status code, otherwise a 404 Not Found if the endpoint was not found, or a 401 Unauthorized status code if there is an issue with the access rights (for instance the API access token is not valid).

The different endpoints below will only describe the <action> part of the endpoint URLs because the rest of the URL is quite static. For List API requests, you have always additionally following parameters available, which can be added in the query part (after the question mark) of the endpoint URL:

  • q: Filters the result by the name of the objects.
  • page: Defines which page of the listing you want to see.
  • showPerPage: Defines how many items per page you want to list.

For Create and Update API requests always ensure to set the Content-Type to application/x-www-form-urlencoded. The relevant data to create or modify are sent in the body section. For instance, if we want to change the name of a customer through the API, we would need to send in the body section the key-value pair: WsCustomer[label]=Customer ABC.

Workspaces

Settings

List all

GET /setting/workspaces

Show one

GET /setting/workspaces/<id>

Show number of assets

GET /setting/workspaces/<id>/assets

Show inventory quality

GET /setting/workspaces/<id>/inventory-quality

List pricecatalog of reseller

GET /pricecatalog/reseller

Update pricecatalog of reseller

PUT /pricecatalog/reseller

To update the pricecatalog of the reseller, use the Pricecatalog key in the body section. Always send the part number and pricecategory of the software license within the body section. The following attributes can be sent:

  • Pricecatalog[part_number]=228-05018
  • Pricecatalog[price]=3.10
    • The purchase price from your reseller
  • Pricecatalog[pricecategory]=corporate
    • You can choose between corporate, academic, or charity.

Show alerts overview

GET /alert/alerts

Data sources

List all

GET /importer/data-sources

Show one

GET /importer/data-sources/<id>

Infrastructure

Virtual machines

List all

GET /infrastructure/vms

Show one

GET /infrastructure/vms/<id>

Hosts

List all

GET /infrastructure/hosts

Show one

GET /infrastructure/hosts/<id>

Devices

The device endpoints are accessing the same data source as the virtual machine and the host endpoints. The only difference is that in the device endpoints there is no distinguishing between the virtual machines and hosts, both are delivered.

List all

GET /infrastructure/devices

The List endpoint has an extra parameter available that can be used in the query part: payload. The payload parameter can be used to filter out devices by their assigned customers. The following parameters can be used:

  • payload[customer.id]: This parameter can be used for filtering devices by the customer ID.
  • payload[customer.label]: This parameter can be used for filtering the devices by the customer name.
  • payload[customer.internal_id]: This parameter can be used for filtering the devices by the customer’s internal ID, which can be set in the customer detail view in the OC Reporter.

Show one

GET /infrastructure/devices/<id|internal_id|agreement_number>

If you want to show a device by the device internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the device instead of the ID.

If you want to show a device by the device agreement number, add additionally the parameter agreement=1 to the query part of the endpoint and enter in the action section of the endpoint the agreement number of the device instead of the ID.

Create one

POST /infrastructure/devices

To create a new device, use the WsDevice key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:

  • WsDevice[label]=Server 1
  • WsDevice[type_id]=host or vm
  • WsDevice[agreement_number]=124-XYZ
  • WsDevice[internal_id]=Xyz
  • WsDevice[cluster_id]=4
  • WsDevice[cluster_label]=Cluster 1
  • WsDevice[host_id]=3
  • WsDevice[host_label]=Host 1
  • WsDevice[operating_system]=Windows Server Datacenter
  • WsDevice[number_cpu]=1
  • WsDevice[number_core]=4
  • WsDevice[status]=active

Update one

PUT /infrastructure/devices/<id|internal_id|agreement_number>

To update the attributes of a device, use the WsDevice key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific device from SPLA, you could send the following key-value pairs within the body section:

  • WsDevice[exclude_spla]=yes
  • WsDevice[exclude_spla_reason]=other
  • WsDevice[exclude_spla_description]=Server out of SPLA scope

Delete one

DELETE /infrastructure/devices/<id|internal_id|agreement_number>

List performance data

GET /infrastructure/devices/performances

The List performance data endpoint has an extra parameter available that can be used in the query part: payload. The payload parameter can be used for instance to filter out performance data by device. The following parameters can be used:

  • payload[device_id]: This parameter can be used for filtering devices by the device ID.
  • payload[device_label]: This parameter can be used for filtering devices by the device name.
  • payload[observation_start]: This parameter can be used for filtering performance data by the observation start date.
  • payload[observation_end]: This parameter can be used for filtering performance data by the observation end date.

List all software by device

GET /infrastructure/devices/<id|internal_id|agreement_number>/softwares

Create one software by device

POST /infrastructure/devices/<id|internal_id|agreement_number>/softwares

To create a new installed software, use the WsInstalledSoftware key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:

  • WsInstalledSoftware[label]=My Custom Software
  • WsInstalledSoftware[status]=active

Update one software by device

PUT /infrastructure/devices/<id|internal_id|agreement_number>/softwares/<sid>

To update the attributes of installed software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific installed software from SPLA, you could send the following key-value pairs within the body section:

  • WsInstalledSoftware[exclude_spla]=yes
  • WsInstalledSoftware[exclude_spla_reason]=other
  • WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope

Delete one software by device

DELETE /infrastructure/devices/<id|internal_id|agreement_number>/softwares/<sid>

Installed software

List all

GET /infrastructure/installed-softwares

Show one

GET /infrastructure/installed-softwares/<id>

Update one

PUT /infrastructure/installed-softwares/<id>

To update the attributes of installed software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific installed software from SPLA, you could send the following key-value pairs within the body section:

  • WsInstalledSoftware[exclude_spla]=yes
  • WsInstalledSoftware[exclude_spla_reason]=other
  • WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope

Delete one

DELETE /infrastructure/installed-softwares/<id>

Clusters

List all

GET /infrastructure/clusters

Show one

GET /infrastructure/clusters/<id>

Create one

POST /infrastructure/clusters

To create a new cluster, use the WsCluster key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:

  • WsCluster[label]=Cluster 1

Update one

PUT /infrastructure/clusters/<id>

To update the attributes of a cluster, use the WsCluster key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific cluster from SPLA, you could send the following key-value pairs within the body section:

  • WsCluster[exclude_spla]=yes
  • WsCluster[exclude_spla_reason]=other
  • WsCluster[exclude_spla_description]=Cluster out of SPLA scope

Delete one

DELETE /infrastructure/clusters/<id>

Datacenters

List all

GET /infrastructure/datacenters

Show one

GET /infrastructure/datacenters/<id>

Scan alerts

List all

GET /infrastructure/scan-alerts

Show one

GET /infrastructure/scan-alerts/<id>

Customers

Users

List all

GET /customer/users

The List endpoint has an extra parameter available that can be used in the query part: payload. The payload parameter can be used to filter out users by their assigned customers. The following parameters can be used:

  • payload[customer.id]: This parameter can be used for filtering users by the customer ID.
  • payload[customer.label]: This parameter can be used for filtering the users by the customer name.
  • payload[customer.internal_id]: This parameter can be used for filtering the users by the customer’s internal ID, which can be set in the customer detail view in the OC Reporter.

Show one

GET /customer/users/<id>

Create one

POST /customer/users

To create a new user, use the WsUser key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:

  • WsUser[username]=Username 1
  • WsUser[status]=active

Update one

PUT /customer/users/<id>

To update the attributes of a user, use the WsUser key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific user from SPLA, you could send the following key-value pairs within the body section:

  • WsUser[exclude_spla]=yes
  • WsUser[exclude_spla_reason]=admin

Delete one

DELETE /customer/users/<id>

List all software by user

GET /customer/users/<id>/softwares

Create one software by user

POST /customer/users/<id>/softwares

To create a new user software, use the WsInstalledSoftware key in the body section. You can use any attribute listed in the Show API request. For instance, you could send the following key-value pairs within the body section:

  • WsInstalledSoftware[label]=My Custom Software
  • WsInstalledSoftware[status]=active

Update one software by user

PUT /customer/users/<id>/softwares/<sid>

To update the attributes of user software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific installed software from SPLA, you could send the following key-value pairs within the body section:

  • WsInstalledSoftware[exclude_spla]=yes
  • WsInstalledSoftware[exclude_spla_reason]=other
  • WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope

Delete one software by user

DELETE /customer/users/<id>/softwares/<sid>

User software

List all

GET /customer/user-softwares

Show one

GET /customer/user-softwares/<id>

Update one

PUT /customer/user-softwares/<id>

To update the attributes of user software, use the WsInstalledSoftware key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to exclude a specific user software from SPLA, you could send the following key-value pairs within the body section:

  • WsInstalledSoftware[exclude_spla]=yes
  • WsInstalledSoftware[exclude_spla_reason]=other
  • WsInstalledSoftware[exclude_spla_description]=Software out of SPLA scope

Delete one

DELETE /customer/user-softwares/<id>

Customers

List all

GET /customer/customers

Show one

GET /customer/customers/<id|internal_id>

If you want to show a customer by the customer internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the customer instead of the ID.

Create one

POST /customer/customers

To create a new customer use the WsCustomer key in the body section. You can set any attribute listed in the Show API request. For instance, if you want to create a customer with a name and an internal ID, you could send the following key-value pairs within the body section:

  • WsCustomer[label]=New Customer ABC
  • WsCustomer[internal_id]=431319
  • WsCustomer[status]=active

Update one

PUT /customer/customers/<id|internal_id>

To update the attributes of a customer, use the WsCustomer key in the body section. You can update any attribute listed in the Show API request. For instance, if you want to modify the customer name and change the customer status, you could send the following key-value pairs within the body section:

  • WsCustomer[label]=Customer ABC
  • WsCustomer[status]=archived

If you want to update a customer by its internal ID, add additionally to your endpoint the parameter internal=1 and enter in the action section of the endpoint the internal ID of the customer instead of the ID.

Delete one

DELETE /customer/customers/<id|internal_id>

Assign device to customer

PUT /customer/<customer-id>/device/<device-id>

Unassign device from customer

DELETE /customer/<customer-id>/device/<device-id>

Assign user to customer

PUT /customer/<customer-id>/user/<user-id>

Unassign user from customer

DELETE /customer/<customer-id>/user/<user-id>

List pricecatalog of all customers or customer groups

GET /pricecatalog/customers
GET /pricecatalog/customer-groups

List pricecatalog of customer or customer group

GET /pricecatalog/customers/<id|internal_id>
GET /pricecatalog/customer-groups/<id|internal_id>

If you want to list the pricecatalog by the internal ID of the customer, add additionally to your endpoint the parameter internal=1 and enter in the action section of the endpoint the internal ID of the customer instead of the ID.

Update pricecatalog of customer or customer group

PUT /pricecatalog/customers/<id|internal_id>
PUT /pricecatalog/customer-groups/<id|internal_id>

If you want to list the pricecatalog by the internal ID of the customer, add additionally to your endpoint the parameter internal=1 and enter in the action section of the endpoint the internal ID of the customer instead of the ID.

To update the pricecatalog of the customer, use the Pricecatalog key in the body section. Always send the part number of the software license within the body section. The following attributes can be sent:

  • Pricecatalog[part_number]=228-05018
  • Pricecatalog[price]=3.10
    • The sale price to the customer
  • Pricecatalog[number_sold]=54
    • Number of sold licenses
  • Pricecatalog[number_lm]=21
    • Number of license mobility
  • Pricecatalog[extra_field_1]=Extra info 1
    • Custom extra field, which you can use for extra information
  • Pricecatalog[extra_field_2]=Extra info 2
    • Custom extra field, which you can use for extra information

License mobility expiry of customers

GET /customer/customers/lm-expiry

If you want to list the expired license mobility agreements, add additionally to your endpoint the parameter withEnded=1.

Contract Licenses

In OC Reporter you have the option of entering so-called "contract licences". Contract licences are licences that have already been sold to the customer. Contract licenses are attached to devices. Contract licenses can have start and/or end dates and appear as sold licences in the generated licence reports.

List all by workspace

GET /contract-licenses

List all by customer

GET /contract-licenses/customer/<id|internal_id>

If you want to show a customer by the customer internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the customer instead of the ID.

List all by device

GET /contract-licenses/device/<id|internal_id|agreement_number>

If you want to show a device by the device internal ID, add additionally the parameter internal=1 to the query part of the endpoint and enter in the action section of the endpoint the internal ID of the device instead of the ID.

If you want to show a device by the device agreement number, add additionally the parameter agreement=1 to the query part of the endpoint and enter in the action section of the endpoint the agreement number of the device indead of the ID.

Show one

GET /contract-licenses/<id>

Create one

POST /contract-licenses/device/<id|internal_id|agreement_number>

To create a new contract lincese, use the WsContractLicense key in the body section. You can send the following key-value pairs within the body section:

  • WsContractLicense[software_license_part_number]=021-08183
  • WsContractLicense[number_of_licenses]=6
  • WsContractLicense[start_date]=2022-04-15
  • WsContractLicense[end_date]=

The key-value pairs "WsContractLicense[start_date]" and "WsContractLicense[end_date]" are optional.

Delete all by workspace

DELETE /contract-licenses

Be careful with this action. It deletes all contract licenses within the workspace.

Delete all by customer

DELETE /contract-licenses/customer/<id|internal_id>

Delete all by device

DELETE /contract-licenses/device/<id|internal_id|agreement_number>

Delete one

DELETE /contract-licenses/<id>

Activities

GET /activity/activities

Because of the big amount of activities, this API endpoint has per default pagination activated. The default pagination will show 300 entries per page. You can filter the activities by using the Activity key in the query parameter section after the question mark.

Reports

Licensing

Note: The API for the licensing report has default payloads to set:

  • payload[month_id]: Defines the relevant month of the report. The month_id is a combination of the YEAR (e.g. 2021) and the MONTH (e.g. 01). For instance, a possible value for month_id would be payload[month_id]=202101, which would generate the report for January 2021.
  • payload[compare_months]: This payload is not required. You can define comma-separated other months you would like to compare with the actual report. For instance, possible values for compare_months would be payload[compare_months]=202012 or payload[compare_months]=202012,202011,202010
  • payload[with_itemized]=1 or 0
  • payload[flat_structure]=1 or 0
  • payload[existing]=1 or 0, if the value is set to 1, it will check if already an existing report with the same month_id exists, if yes, it will not regenerate a new report, but serve the existing one. If the value is set to 0, it will try to generate a new report, if the 5th of the next month is not exceeded.

SPLA usage report for reseller

With observation period for the full month (recommended)

GET /report/licensing/spla-usage-reseller?…&payload[month_id]=202007

With a date range

GET /report/licensing/spla-usage-reseller?…&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31

Without observation period

GET /report/licensing/spla-usage-reseller?…&payload[without_high_water_mark]=1

Usage report for customer billing

With observation period for the full month (recommended)

GET /report/licensing/spla-usage-customer?…&payload[month_id]=202007

With a date range

GET /report/licensing/spla-usage-customer?…&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31

Without observation period

GET /report/licensing/spla-usage-customer?…&payload[without_high_water_mark]=1

For a specific customer

GET /report/licensing/spla-usage-customer?…&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31&payload[customer_ids]=<customer-id>

Response of the usage report

When you generate your usage report, it presents information grouped in the

following categories:

  • summaryLicenses: The summaryLicenses category shows a summary of all calculated usage licenses. We recommend using the payload[flat_structure]=1 in the API request URL as a parameter to iterate easier through the results. Each item inside an object represents one license product.
  • itemized: The itemized category lists all licenses in detail. The itemized category is only loaded, when the payload[with_itemized]=1 is added to the API request URL.
  • customersServersSoftware
  • missingUnitPrices: If licenses are calculated for license agreements where the purchase price is missing, you can find them under this category. Each item in an object presents the part number and the price category of a specific license. You must add the purchase price for each license or the license won’t be calculated for the usage reports. The purchase prices for each calculated license are required. The system uses the purchase prices to calculate break-even points informing which license is the most cost-effective.

Delete one

DELETE /report/licensing/<id>

Cloud

Cloud VM Cost Adviser

  • payload[customer_id]: If the payload is set, then the report will only be generated for the defined customer. If the payload is not set, the report will be generated for all available customers.
  • payload[cloud_provider]: Set the specific cloud provider for who you want to generate the report. You can set multiple cloud providers comma separated. If the payload is not set, it will generated the report for all available cloud providers. Available values to set:
    • 10_ms_azure: Microsoft Azure
    • 20_amazon_web_services_aws: Amazon Web Services (AWS)
GET /report/cloud/cloud-vm-cost-adviser?…&payload[cloud_provider]=10_ms_azure&payload[customer_id]=10

Data Export

GET /report/data-export?..&payload[category]=<category>&payload[start_date]=2020-07-01&payload[end_date]=2020-07-31

The <category> parameter represents which category you want to export the data. You can enter one of the following categories:

  • WsDatanceter
  • WsCluster
  • WsDevice
  • WsInstalledSoftware-server
  • WsUser
  • WsInstalledSoftware-user
  • WsCustomer
  • WsAssignedDevice
  • WsCustomerGroup
  • WsScanAlert
  • WsScanner

Related articles