Nuix SDK – Quick Start Guides

Getting Started: Set Up your Development Environment

Mon, 08 Mar 2021 00:00:00 +0000

Before proceeding with the steps outlined below, ensure that the following prerequisites have been completed:

Nuix RESTful Service is installed and running.
Access to Nuix Licensing is configured using any of the following options:
- Nuix Management Server (NMS)
- Nuix Cloud License Server (CLS)

You will also need to know the following details about your installation.

The server location of your REST installation.
- Default location: <localhost>:8080/nuix-restful-service/svc/
- This URL is used throughout the provided examples to make calls to the API.
The location of the API reference documentation.
- Default location: <localhost>:8080/nuix-restful-service/svc/docs

Nuix RESTful Service is a language agnostic tool capable of interpreting calls over HTTP(s) using the method of your choice. To explore the API, any tool capable of performing HTTP requests can be used.

Postman

For the purposes of these quick start topics, simple cURL commands are provided that can be run within Postman. To use Postman, visit the following URL and download the API client for the operating system you are using.

https://www.postman.com/downloads/

Once downloaded, run the installer to setup Postman on your computer. Details about the installation process can be located on the Postman website.

https://learning.postman.com/docs/getting-started/installation-and-updates/

After the installation completes, launch the application by clicking the Postman icon on your desktop.

Import the OpenAPI Specification

The Nuix RESTful Service API documentation can be imported directly into Postman using any of the following methods. The steps outlined below are based on Postman Version 7.36.4.

Option 1: Run in Postman

To get started quickly, click the Run in Postman button below and follow the prompts to import the complete API directly into Postman with just a few clicks.

Option 2: Link Import

Use the following procedure to import the Nuix RESTful Service API into Postman using a link to the API specification:

Navigate to the Nuix RESTful Service reference documentation to locate a direct link to the OpenAPI specification.

Default docs location: <localhost>:8080/nuix-restful-service/svc/docs
Right-click the URL below the heading at the top of the page, then select Copy link address to copy the location of the openapi-docs.json specification file.
Within Postman, expand the File menu, and then click import.
From the Import window, select the Link tab. Paste the address you copied in Step 2 into the URL field, and then click Continue.
Confirm the details of the import and make the following additional selections:
- Under the Link this collection as menu, select Integration Test.
- Click Show advanced settings and confirm the following selections:

Advanced Option	Recommended Setting
Naming requests	`Fallback`
Request parameter generation	`Example`
Response parameter generation	`Example`
Folder organization	`Tags`

Click Import.

When the import is complete, a new collection named Nuix REST-API Reference will be available from the Collections tab. The available endpoints are organized according to how they are listed in the API reference documentation.

Option 3: File Import

If you do not have a running instance of Nuix RESTful Service, but have previously downloaded the specification in either openapi.yaml or openapi-docs.json format, you can upload the API documentation directly into Postman with the specification that you have saved using the following procedure.

Within Postman, expand the file menu, and then click Import.
From the File tab, click Upload Files and then locate and select a previously downloaded API documentation file. (openapi.yaml or openapi-docs.json)
Confirm the details of the import and make the following additional selections:
- Under the Link this collection as menu, select Integration Test.
- Click Show advanced settings and confirm the following selections:

Advanced Option	Recommended Setting
Naming requests	`Fallback`
Request parameter generation	`Example`
Response parameter generation	`Example`
Folder organization	`Tags`

Click Import.

Advanced Postman Setup

Postman provides an interface that allows you to create and test calls to an API. Postman also allows you to configure variables for commonly used parameters that can be used to streamline your workflow when constructing API calls.

Use the following procedure to setup a few basic configurations in your Postman installation:

With Postman open, select an existing collection or click on New Collection to create a location to save any API calls that you create for the Nuix RESTful Service.
- Provide a name for the new collection and optionally a description.
Select the Variables tab and define the following variables based on your installation:

Variable	Current Value
`base-url`	The URL of your Nuix RESTful Service installation. Default URL: http://127.0.0.1:8080/nuix-restful-service/svc
`nuix-auth-token`	The authorization token that was issued to you when a license is acquired. Note: Since a license has not yet been acquired, leave this field empty.

Note

The variable values identified in the table map to parameters used in the Nuix RESTful Service API.

Click Create to finalize the new collection.

The newly created collection will be displayed in the left sidebar of Postman under the Collections tab. As you create and test calls to the REST API, you can save them to your newly created collection and access them from this location within Postman.

To create a new request, click the + button located at the top of the builder window.

To save a request to your Postman collection, use the following procedure:

Expand the Save button drop-down menu next to the URL input field and select Save As from the menu.
Provide a Request name, such as Server Status, for the call.
Select the Collection to save the request in, then click Save.

Getting Started: Checking Server Status

Thu, 22 Apr 2021 00:00:00 +0000

Before making any calls to the Nuix RESTful Service API, it is best practice to first ensure that the service is running and available.

The Nuix RESTful Service server status can be checked using the following GET request to the /about endpoint.

curl -X GET "http://127.0.0.1:8080/nuix-restful-service/svc/about" -H "accept: application/vnd.nuix.v2+json"

{
 "server" : "http://localhost:8080/nuix-restful-service/svc",
 "serverId" : "rest-oem-server",
 "startupTime" : null,
 "nuixRestfulVersion" : null,
 "engineVersion" : null
}

If the service is available, a response similar to this example will be returned.

Note: In this example, some of the response values have returned null values. These values are intentionally not returned because the request was submitted without an authentication token.

Getting Started: Manage Licenses with REST

Thu, 22 Apr 2021 00:00:00 +0000

An authentication token is required to access most endpoints within the Nuix RESTful Service API. To get an authentication token, a request must be submitted to the API to retrieve a license from your configured NMS instance. If the requested license is available on the licensing server, an authentication token will be issued in the request response. This token can then be used during your session to make authenticated calls to the API.

Note: Based on the configuration of your installation of Nuix RESTful Service, your authentication token may expire if your session becomes inactive. If this occurs, a new token must be retrieved using the steps within this topic.

Within this topic, you’ll learn how to:

Identify which Nuix license types are available for use.
Request an authentication token.
Release your license to end your session.

License Availability

Nuix offers several different license types that provide various functionality for different use cases. When submitting a request to retrieve an authentication token, you may want to know what license types are available to you.

Check which Nuix license types are available on your configured NMS instance using the following GET request to the /licenses endpoint.

curl -X GET "http://127.0.0.1:8080/nuix-restful-service/svc/licenses" -H "accept: application/vnd.nuix.v1+json"

{
  "shortname": "enterprise-workstation",
  "count": 8,
  "configuredCount": 10,
  "description": "Nuix eDiscovery Workstation",
  "workers": 6,
  "configuredWorkers": 10,
  "audited": false,
  "auditThreshold": 0,
  "source": null,
  "type": null,
  "location": null,
  "expiry": null,
  "legalHoldHoldCountLimit": null,
  "concurrentUserLimit": null,
  "canChooseWorkers": null
}

If the license server is accessible, a response similar to this shortened example will be returned. The response includes details about each license type that exists on the configured licensing server.

Identify the license type that meets the needs of your job, then locate its associated short name. The short name is used during license acquisition to request a specific license type.

License Acquisition

A license is required in order to gain full access to the Nuix REST API. When you request a license, you are issued an authentication token that can then be used in all subsequent requests to the API.

Submit a request to retrieve a license and authentication token from your licensing server using the following PUT request to the /authenticatedUsers/login endpoint.

curl -L -X PUT 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/login' \
-H 'Content-Type: application/json' \
--data-raw '{
    "username": "user1",
    "password": "password",
    "licenseShortName": "enterprise-workstation",
    "workers": 2
}'

{
  "username": "user1",
  "authToken": "49e225d7-b88d-4d1b-9cbc-296e83706a60",
  "licenseShortName": "enterprise-workstation",
  "workersGranted": 1
}

In this example, four parameters are submitted in the body of the request as JSON.

username: The username for an account that has access to the licensing server.
password: The password associated with the username.
licenseShortName: (Optional) The short name of the license to be retrieved.
workers: (Optional) The number of workers to request with the license.

Both licenseShortName and workers are optional parameters. If left undefined, the first license offered by the licensing server will be claimed. Additionally, if the selected license type supports the use of workers, a default value of one or two workers, assigned by the Nuix Engine, will also be assigned.

Note: Workers are a consumable entity within your environment like licenses. If no workers are available at the time that a license is requested, no workers will be assigned. Similarly, if many workers are requested, but only a few are available, a subset of the total requested workers equal to the number of available workers will be assigned.

The response from the license acquisition request displays the issued authentication token, retrieved license type, and the number of workers that have been assigned to the license.

After obtaining the authentication token, provide it within the header of all subsequent calls to make authenticated requests to the API.

For example:

When checking the server status by calling the /about endpoint, if the request is made using an authentication token, the response will include details about the REST server instead of null values.

curl -L -X GET 'http://127.0.0.1:8080/nuix-restful-service/svc/about' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "server" : "http://127.0.0.1:8080/nuix-restful-service/svc",
    "serverId" : "rest-oem-server",
    "startupTime": 1602193993435,
    "nuixRestfulVersion": "9.4.0",
    "engineVersion": "${nuix-engine}"
}

License Revocation

When you are finished making calls to the Nuix RESTful Service API, it is best practice to end your session. Performing this action revokes your authentication key and returns your license and any assigned workers back to the licensing server for other users to consume.

Submit a DELETE call to the /authenticatedUsers/{username) endpoint, specifying the username used to log in and your authentication token in the header of the request to revoke your license and authentication token.

curl -L -X DELETE 'http://127.0.0.1:8080/nuix-restful-service/svc/authenticatedUsers/user1' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "success": true
}

When this request is performed, if your session is active with running or queued functions, you will be asynchronously logged out. This default behavior allows the session to remain active until the functions have completed. At that time, the session will end, and your license will be returned.

Getting Started: Manage Cases within your Inventory

Thu, 22 Apr 2021 00:00:00 +0000

All data that is ingested and processed using the Nuix Engine is done so within a Nuix case. The case acts as a container for the collections of data and evidence related to an investigation. Nuix supports two types of cases:

Simple: A single case that contains all data for an investigation.
Compound: A collection of two or more related simple cases that can be accessed concurrently as a single large case.

After choosing the type of case best suited for your purpose, you can ingest evidence and begin any required post processing activities. All cases that are created are saved within your case inventory, which was defined during the installation of Nuix RESTful Service.

Within this topic, you’ll learn how to:

Create a new case.
View existing cases.
Close a case.
Delete a case.

Creating a Case

New cases can be created by submitting a POST request to the /cases endpoint. Use the following request to create a simple case. For information on creating other case types, such as compound or elastic-based cases, see the Nuix RESTful Service API reference documentation.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/cases' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \
-H 'Content-Type: application/json' \
--data-raw '{
  "compound": false,
  "location": "inventory0",
  "name": "MyNuixCase",
  "description": "A simple case created using the REST API",
  "investigator": "Your Name"
}'

{
    "caseId": "0eedda2d297046ae8e67fbda9f192df9",
    "name": "MyNuixCase",
    "path": "C:\\Program Files\\Nuix\\Nuix RESTful Service\\cases\\MyNuixCase",
    "description": "A simple case created using the REST API",
    "investigator": "Your Name",
    "creationDate": 1602818339843,
    "compound": false,
    "elastic": false,
    "binaryStoreLocation": "",
    "indexId": "",
    "caseSize": 0,
    "casePathParent": "C:\\Program Files\\Nuix\\Nuix RESTful Service\\cases",
    "caseInvestigationTimeZone": "America/New_York",
    "hasExclusions": null,
    "hasNuixSystemTags": null,
    "hasProductionSets": null,
    "hasCalculatedAuditSize": null,
    "casePath": "C:\\Program Files\\Nuix\\Nuix RESTful Service\\cases\\MyNuixCase",
    "caseName": "MyNuixCase",
    "caseCreationDate": 1602818339843,
    "caseDescription": "A simple case created using the REST API",
    "caseInvestigator": "Your Name"
}

In the example above, five parameters are submitted in the body of the request as JSON as well as an authentication token in the header of the request.

compound: The type of case to create. A value of false will create a simple case.
location: A relative or absolute path that is within the defined inventory location used by REST where the case will be saved. A value of inventory0 references the first defined inventory location within your installation of REST.
name: A unique name to identify the case. This value also defines the name of the directory which contains the case on the file system.
description: (Optional) A brief description to indicate the contents or purpose of the case.
Investigator: The name of the person creating the case.

After submitting the request, details about the newly created case are included in the response, including the caseId of the case. The caseId value is a required parameter in all requests involving a case.

Identifying Existing Cases

If cases have already been created within your inventory, they can be identified by submitting a GET request to the /inventory/digest endpoint with your authentication token. Doing so will return information for all cases that exist within your configured inventory locations.

This request can be helpful if you need to look up details about a case, such as its caseId.

curl -L -X GET 'http://127.0.0.1:8080/nuix-restful-service/svc/v1/inventory/digest' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \

[
    {
        "caseId": "0eedda2d297046ae8e67fbda9f192df9",
        "name": "MyNuixCase",
        "path": "C:\\ProgramData\\Nuix\\NuixCases\\MyNuixCase",
        "description": "A case created using the REST API",
        "investigator": "Your Name",
        "creationDate": 1609909619982,
        "compound": false,
        "elastic": false,
        "binaryStoreLocation": "",
        "indexId": "",
        "productName": "Nuix",
        "version": "8.7.1",
        "isOpen": true,
        "childCases": [],
        "url": "http://10.101.100.66:8080",
        "serverId": "fdfc0544-4421-40df-bbd6-a200371b200d"
    }
]

Closing a Case

Any time a new case is created, or an existing case is used in a request, the case is considered open. When cases are opened, they become locked to prevent other users from accessing the case at the same time.

The status of a case can be determined by calling the /inventory/digest endpoint or the /inventory/{caseId} endpoint, if the caseId is known, to retrieve details about the case.

The response body to these requests includes the following parameter.

"isOpen": true

A value of true indicates that the case is open.

When you are finished working with a case, it should be closed so that it becomes unlocked and available to other users.

To close a case, submit a POST request to the /cases/{caseId}/close endpoint.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/cases/0eedda2d297046ae8e67fbda9f192df9/close' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "success": true
}

Deleting a Case

To delete a case from your inventory, submit a DELETE request to the /cases/{caseId} endpoint.

curl -L -X DELETE 'http://127.0.0.1:8080/nuix-restful-service/svc/cases/0eedda2d297046ae8e67fbda9f192df9' \
-H 'nuix-auth-token: fabbd5b7-8e4d-4af8-a970-feed76a34f46'

{
    "caseId": "0eedda2d297046ae8e67fbda9f192df9",
    "success": true,
    "childCases": null
}

Getting Started: Process Data into a Nuix Case

Thu, 22 Apr 2021 00:00:00 +0000

After acquiring a license and creating a case, you can then begin ingesting data into the case using the Nuix Engine. Nuix RESTful Service provides multiple endpoints that can be used to ingest data from different data sources. These endpoints are described within the Processing category of the Nuix RESTful Service API reference documentation.

Within this topic, you’ll learn how to:

Perform a simple ingestion.
Checking the status of the request.

Ingesting Data into a Case

When processing data into a Nuix case, there are many configurable parameters that can be used to tailor what data is retrieved, how it is processed, where it is stored, and what resources should be used to perform the work. The settings used are often determined by the type of investigation being performed and the level of detail that is required.

Details about these parameters can be found within the reference documentation for the endpoint.

For the purposes of this example, a simple ingestion can be performed by submitting a POST request to the /cases/{caseId}/evidence/file endpoint. This request ingests the contents of a single file or directory into an evidence container within the case using basic processing settings.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/v1/cases/0eedda2d297046ae8e67fbda9f192df9/evidence/file' \
-H 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60' \
-H 'Content-Type: application/json' \
--data-raw '{
  "container": {
    "custodian": "John Doe",
    "name": "Evidence Container 1"
  },
  "target": {
    "path": "C:/LocationOfData"
  },
  "processorSettings": {
    "analysisLanguage" : "en",
    "processText" : true,
    "reportProcessingStatus": "physical_files",
    "traversalScope" : "full_traversal"  
  }
}'

{
    "functionKey": "72744ec6-6de1-488c-bbec-ff27b64974e3",
    "location": "http://127.0.0.1:8080/nuix-restful-service/svc/v1/asyncFunctions/72744ec6-6de1-488c-bbec-ff27b64974e3"
}

In this example, the following parameters are submitted in the body of the request as raw data.

custodian: The name of the person who owns the data being ingested.
name: The name of the evidence container where the custodian’s data is being ingested.
path: The absolute path to the file or directory being ingested.
analysisLanguage: The language to use for text analysis when indexing the data.
processText: Store and index the text of data items.
reportProcessingStatus: Calculates the physical file size of the evidence before ingestion. This data can then be used to report the progress of the ingestion.
traversalScope: Indicates what files should be processed. The full_traversal value ensures that all loose files and forensic images are processed, including their contents.

Any number and combination of parameters can be submitted in the request. If you find that you use consistent processor settings when performing ingestions, an external processing profile can also be used to supply the settings rather than defining them individually within the body of the request.

To use a processing profile, specify the name of the profile using the processingProfile parameter. The profile must exist within the ..\nuix-engine\user-data\Processing Profiles directory of your REST installation.

See the reference documentation for the endpoint to learn more about available parameters.

After submitting the request to perform an ingestion, a GET request to the /asyncFunctions/{key} endpoint using the returned functionKey can be used to retrieve details about the ingestion request, including:

The status of the function.
Details about the request.
The processing settings used.
A summary of the processed data.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/72744ec6-6de1-488c-bbec-ff27b64974e3' \
--header 'nuix-auth-token: 49e225d7-b88d-4d1b-9cbc-296e83706a60'

{
    "done": true,
    "cancelled": false,
    "result": true,
    "token": "49e225d7-b88d-4d1b-9cbc-296e83706a60",
    "functionKey": "72744ec6-6de1-488c-bbec-ff27b64974e3",
    "progress": 135591,
    "total": 135591,
    "percentComplete": 100.0000,
    "updatedOn": 1610047993132,
    "status": null,
    "statusId": null,
    "requestTime": 1610047968056,
    "startTime": 1610047968056,
    "finishTime": 1610047996497,
    "caseId": "8ca047e086aa4497bc311ef5cb4bada7",
    "caseName": "MyNuixCase",
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Evidence Ingestion Function",
    "caseLocation": "C:\\ProgramData\\Nuix\\NuixCases\\MyNuixCase",
    "requestor": "user1",
    "action": "AsyncBulkIngestionFunction",
    "options": {
        "reloadQuery": null,
        "processorSettings": {
            "processText": true,
            "processLooseFileContents": null,
            "processForensicImages": null,
            "analysisLanguage": "en",
            "stopWords": null,
            "stemming": null,
            "enableExactQueries": null,
            "extractNamedEntities": null,
            "extractNamedEntitiesFromText": null,
            "extractNamedEntitiesFromProperties": null,
            "extractNamedEntitiesFromTextStripped": null,
            "extractShingles": null,
            "processTextSummaries": null,
            "calculateSSDeepFuzzyHash": null,
            "detectFaces": null,
            "extractFromSlackSpace": null,
            "carveFileSystemUnallocatedSpace": null,
            "carveUnidentifiedData": null,
            "carvingBlockSize": null,
            "recoverDeletedFiles": null,
            "extractEndOfFileSlackSpace": null,
            "smartProcessRegistry": null,
            "identifyPhysicalFiles": null,
            "createThumbnails": null,
            "skinToneAnalysis": null,
            "calculateAuditedSize": null,
            "storeBinary": null,
            "maxStoredBinarySize": null,
            "maxDigestSize": null,
            "digests": [],
            "addBccToEmailDigests": null,
            "addCommunicationDateToEmailDigests": null,
            "reuseEvidenceStores": null,
            "processFamilyFields": null,
            "hideEmbeddedImmaterialData": null,
            "reportProcessingStatus": null,
            "workerItemCallback": null,
            "workerItemCallbacks": null
        },
        "evidence": [
            {
                "guid": null,
                "name": "Evidence Container 2",
                "customMetadata": null,
                "encoding": null,
                "custodian": "Jane Doe",
                "timeZone": null,
                "description": null,
                "locale": null,
                "files": [
                    {
                        "path": "C:/LocationOfData"
                    }
                ],
                "exchangeMailboxes": null,
                "s3Buckets": null,
                "sqlServers": null,
                "enterpriseVaults": null,
                "sharepointSites": null,
                "mailStores": null,
                "loadFiles": null,
                "centeraClusters": null,
                "splitFiles": null,
                "dropboxes": null,
                "sshServers": null
            }
        ],
        "localWorkerCount": 2,
        "repositories": [],
        "parallelProcessingSettings": {
            "workerCount": null,
            "workerMemory": null,
            "workerTemp": null,
            "brokerMemory": null,
            "workerBrokerAddress": null,
            "useRemoteWorkers": false,
            "embedBroker": true
        },
        "rescanEvidenceRepositories": false,
        "loadProcessingJob": {
            "casePath": "C:\\ProgramData\\Nuix\\NuixCases\\MyNuixCase",
            "jobGuid": "989b79fe-43e6-4fa4-9466-19ea3d5ef644",
            "processingMode": "Load",
            "startDate": 1610047968374,
            "workerCount": 2,
            "finished": true,
            "paused": false,
            "masterAddress": "10.20.100.50",
            "bytesProcessed": 135591,
            "itemsProcessed": 12,
            "jobSizeTotalBytes": 135591
        }
    },
    "participatingInCaseFunctionQueue": true,
    "processedBy": "fdfc0544-4421-40df-bbd6-a200371b200d",
    "errorMsg": null
}

Getting Started: Checking the Status of a Function

Thu, 22 Apr 2021 00:00:00 +0000

When submitting requests to perform long running asynchronous tasks, a simple response like the following example is returned which includes a functionKey and location.

curl --location --request POST 'http://localhost:8080/nuix-restful-service/svc/v1/cases/43b070164ce8453ca30ed9e2dfcce67b/evidence/file' \
--header 'nuix-auth-token: 9729a460-eda7-48dc-ba70-d12b3aae3c8d' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
   "processorSettings": {
   	"storeBinary": true
   },
   "target": {
    "path": "/Engines/9.0.0.171/doc"
  }
}
'

{
    "functionKey": "814388bb-d0fe-4a75-a4cb-02d1f46213e2", 
    "location": "http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/814388bb-d0fe-4a75-a4cb-02d1f46213e2"
}

The functionKey is a unique identifier for the function that can be used to query its status. The location URL provides a direct request to the /asyncFunctions/{key} endpoint. Making calls to this endpoint with the returned functionKey will return details about the associated function.

While an asynchronous function is running, this endpoint can by queried to check the status of the function and eventually retrieve the final output of the request.

Note

The results of asynchronous functions, such as ingestion, are only maintained for five minutes after the completion of the function. To change this time period, modify the asyncFunctionResultRetention property within the Application Settings.

Getting Started: Retrieving Diagnostics

Thu, 22 Apr 2021 00:00:00 +0000

Nuix RESTful Service provides the ability to retrieve diagnostics at any time to troubleshoot issues that may be impacting the health of the service. When requested, a ZIP archive is generated that contains the following diagnostics:

Logs
Product versions
Configured environment variables
System properties
Licence properties
Storage details
Process information
JVM arguments and settings
Installed and missing dependencies

To perform this action, submit a POST request to the /system/diagnostics endpoint to retrieve the data asynchronously. The diagnostics endpoint can also be called using the GET method to retrieve results synchronously.

Tip

If retrieving diagnostics from a clustered environment, the request must be performed asynchronously using the POST method.

curl -L -X POST 'http://127.0.0.1:8080/nuix-restful-service/svc/system/diagnostics?includeResourceDetails=false' \
-H 'nuix-auth-token: cf472e00-89c2-4006-ba59-4949b5dafce8'

{
    "functionKey": "a80b5f19-c4f0-4a32-8ef4-e43ff6bea980",
    "location": "http://127.0.0.1:8080/nuix-restful-service/svc/v1/asyncFunctions/a80b5f19-c4f0-4a32-8ef4-e43ff6bea980"
}

As an asynchronous request, a functionKey is returned with the request so its progress can be tracked.

Using the functionKey, call the /asyncFunctions/{key} endpoint, identified by the returned location value, to retrieve information about the function, including:

The status of the function.
The location of the generated diagnostics, when complete.
User and server information.

When diagnostics are retrieved from a cluster, a single ZIP archive is generated. Within the archive, diagnostics for each node are provided within subfolders labeled using the node’s IP address.

curl --location --request GET 'http://localhost:8080/nuix-restful-service/svc/v1/asyncFunctions/a80b5f19-c4f0-4a32-8ef4-e43ff6bea980' \
--header 'nuix-auth-token: cf472e00-89c2-4006-ba59-4949b5dafce8'

{
    "done": true,
    "cancelled": false,
    "result": {
        "key": "e9924103-d9e2-4901-b82f-60b60d47bd33",
        "location": "http://10.30.100.58:8080/nuix-restful-service/svc/v1/downloads/e9924103-d9e2-4901-b82f-60b60d47bd33",
        "members": [
            {
                "member": "[127.0.0.1]:5601",
                "exception": null,
                "additionalInfo": ""
            }
        ]
    },
    "token": "cf472e00-89c2-4006-ba59-4949b5dafce8",
    "functionKey": "a80b5f19-c4f0-4a32-8ef4-e43ff6bea980",
    "progress": 1,
    "total": 1,
    "percentComplete": 100.0000,
    "updatedOn": 1611610309395,
    "status": null,
    "statusId": null,
    "requestTime": 1611610305962,
    "startTime": 1611610305962,
    "finishTime": 1611610309396,
    "caseId": null,
    "caseName": null,
    "hasSuccessfullyCompleted": true,
    "friendlyName": "Distributed System Diagnostic Function",
    "caseLocation": null,
    "requestor": "nuixuser",
    "action": "MultiNodeAsyncSystemDiagnosticsFunction",
    "options": null,
    "participatingInCaseFunctionQueue": false,
    "processedBy": "637edbff-3e1c-4f63-921e-da022a763fbf",
    "errorMsg": null
}