REST API

Nanitor offers a REST API on top of its application. To be able to use the REST API you will need an API key. Additionally, make sure the API service on the Nanitor server is up and running (systemctl status nanitor-system-api.service).

The instructions below explain how you can retrieve an API key to leverage the Nanitor API and will give a basic functional example with a troubleshooting section in case the API call returns an unexpected error.

Obtaining an API Key

Using the REST API needs an API Key that can be obtained from a Nanitor administrator. From the Organization Management menu, select API Keys:

Create a new API key by clicking the Create API Key button on the top right:

Give the API Key a descriptive name. You can choose between a key with read-only access or a key with both read and write access.

Now you need to copy the API key and keep it in a safe place since it can't be revealed again! If you lose it you need to delete it and create a new one.

Deleting an API Key

In the list of API keys go to the API key that you need to remove. In the Actions column select Delete from the dots menu.

Confirm the delete action by typing delete in the confirmation field.

Basic usage of the REST API

After having retrieved an API key you are now able to use the API. The basic endpoint for any API endpoint is https://<yournanitorinstnce>/system_api followed by the actual endpoint as listed in the documentation at https://api-docs.nanitor.com/

A valid REST API call needs to include the API token inside the header of the request (e.g. -header 'Authorization: Bearer {yourapikey}') and the REST API endpoint (e.g. /assets)). To simply pull a list of all assets using the curl command line tool, you would do:

curl  --request GET 'https://<yournanitorinstnce>/system_api/assets/  -header 'Authorization: Bearer <yourapikey>'

Available REST endpoints

All available REST API endpoints are documented in the Nanitor REST API documentation:

https://api-docs.nanitor.com/

Updating Asset Custom Fields

Custom field values can be set from a script. This is useful when the values come from another system and should be kept in sync automatically. See Custom fields in CSV import in the User Guide for importing custom field values from a CSV file.

The API has these endpoints:

List custom fields to find the ID of each custom field. The same section describes how to retrieve a single field.
Update an asset's custom field to set or clear the value of one field on one asset.

Reading custom fields requires an API key with read access. Updating a value requires an API key with read and write access. Create the key as described in Obtaining an API Key.

Updating a value sends a POST request to /system_api/assets/<asset-id>/custom_fields with a JSON body that contains the field_id and a list of values. For a select field, each value must match one of the field's options exactly.

curl --request POST 'https://example.nanitor.com/system_api/assets/<asset-id>/custom_fields' \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{"field_id": <field-id>, "values": ["Data Center"]}'

Sending an empty list of values clears the field. Fields other than multi-select fields accept at most one value, and a request with more than one value is rejected. Values are validated against the type of the custom field, and a request with an invalid value is rejected. The exception is multi-select fields. For those, the request replaces the whole set of values. Values that are not valid options are skipped, and values already on the asset that are not in the request are removed. A request that contains only invalid options therefore clears the field.

Troubleshooting

When you receive a 5xx error it might be possible that the API service is not enabled and/or not running. Log into the console of the Nanitor server and run these commands as a root user:

systemctl enable nanitor-system-api.service
systemctl start nanitor-system-api.service