Examples for Lucidum API v2

This chapter includes examples of the Lucidum API v2.

For details on the syntax for the Lucidum API v2, see the chapter on Endpoints.

Query Metadata #

In this example, we query the list of fields for assets from the Lucidum database. The response includes the same list of fields for an asset that you see in the New Query page or Edit Query page when you click on the Field field (Explore button > Query Builder page> New Query/Edit Query page > Field field).

The response includes a description of each field and its data type.

cURL #

curl --location 'https://test-host.company.com/CMDB/v2/data/metadata/asset' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer quoVnYQeDNicAOywkOKq'
  • Line 1. The cURL call. The method defaults to GET. The URL is host name plus the endpoint for this API.

  • Line 2. The header specifies to return results in JSON.

  • Line 3. The header specifies to use a Bearer Token for authentication and provides the bearer token.

Include the lines that start with “–header” in each call to the Lucidum API v2.

Python #

import requests
url = "https://test-host.company.com/CMDB/v2/data/metadata/user"
headers = {'Authorization': 'Bearer quoVnYQeDNicAOywkOKq'}
response = requests.request("GET", url, headers=headers, verify=False)
print(response. Text)
  • Line 2. The method defaults to GET. The URL is host name plus the endpoint for this API.

  • Line 3. The header specifies to use a Bearer Token for authentication and provides the bearer token.

Response #

The response includes over 3000 lines, so this is a sample of the response:

{
    "metadata": [
        {
            "fieldName": "Asset with SSH",
            "fieldDescription": "Asset with SSH added by tag manager",
            "dataType": "String",
            "displayName": "Asset with SSH",
            "fieldGroup": "Smart Labels"
        },
        {
            "fieldName": "File_Bucket",
            "fieldDescription": "File bucket name",
            "dataType": "List",
            "displayName": "Cloud Bucket",
            "fieldGroup": "Data"
        },
        {
            "fieldName": "Customer",
            "fieldDescription": null,
            "dataType": "String",
            "displayName": "Customer",
            "fieldGroup": "Extra Fields"
        },
        {
            "fieldname": "Metric_Space",
            "fieldDescription": "Cloudwatch metric space",
            "dataType": "String",
            "displayName": "Cloud Watch Metric Space",
            "fieldGroup": "Compliance"
        },
]
}

For each field, the response includes:

  • fieldname. Name to use with the Lucidum API v2.

  • fieldDescription. A description of the field.

  • datatype. The data type for the field.

  • displayName. How the field name appears in the Lucidum interface.

  • fieldGroup. The group where the field appears in the Lucidum interface.

Simple Query #

This example is a simple query to the Lucidum Database, using the endpoint /CMDB/v2/data/cmdb.

This endpoint sends queries to the Lucidum database, using fields, operators, AND statements, and OR statements, as you would in the Query Builder in the Lucidum UI.

This API uses the POST method. If you are using cURL, specify “-X POST”

Simple Query: Request Body JSON #

{
"table":"asset",
"query":[
[
{
"searchFieldName":"Data_Classification",
"operator":"==",
"type":"String",
"value":"Restricted"
}
]
]
}
"paging": {
"page": 0,
"recordsPerPage": 20
}
}
  • Line 2. Define the table parameter. In this example, we will query the “asset” table

  • Line 3. Define the query parameter. Line

  • Line 6. the record must include the field name “Data_Classification”

  • Line 7. the “Data_Classification” field contains an exact match

  • Line 9. to the value “Restricted”

  • Line 8. Data_Classification has a data type of String

  • Line 14-17. Specify pagination

Simple Query: Response #

The response includes the entire asset record for each asset where Data_Classification is “Restricted”.

Each asset includes over 300 lines in the response. Here is an abbreviated response:

{
"totalRecords": 465,
"data": [
{
"_id": "6461f100081577f5c85d7bc6",
"_time": 1684139969,
"run_time": 1684139969,
"Asset_Name": "I-087EBEBD8628B8A23",
"Is_Public": null,
"Last_Discovered_Datetime": 1684139334,
"Source_User_Name": [
"api.user",
"charles",
],
"Services": [
"https"
],
"FQDN": [
"ip-172-21-50-93.ec2.internal"
],
"MAC_Address": [
"16:81:1b:83:f3:b5"
],
"IP_Address": [
"172.21.50.93"
],
"Open_Port_List": [
"443"
],
"Host_Name": [
"I-087EBEBD8628B8A23"
],
},
{
"_id": "6461f100081577f5c85d7bcf",
"_time": 1684139969,
"run_time": 1684139969,
"Asset_Name": "I-0CE13EE75724B2BE7",
"Is_Public": 1.0,
"Last_Discovered_Datetime": 1684138734,
"Source_User_Name": [
"KY"
],
"Services": [
"https",
],
"FQDN": [
"ip-172-16-50-31.us-west-1.compute.internal"
],
"MAC_Address": [
"06:93:56:6d:85:99"
],
"IP_Address": [
"172.16.50.31",
"52.52.161.135"
],
"Open_Port_List": [
"443",
],
"Host_Name": [
"I-0CE13EE75724B2BE7"
],
}
],
"totalPages": 24,
"recordsPerPage": 20,
"page": 0
}

Query with AND #

AND means that the results must meet all the criteria in a multi-part query.

In this example, our multi-part query includes two criteria. To specify AND, we enclose the first part of the AND query with “[“ and “],” (open square bracket and close square bracket followed by a trailing comma). We enclose the second part of the AND query with “[“ and “]” (open square bracket and close square bracket with no trailing comma).

Note that you can include as many AND statements in a query as you require; you are not limited to two criteria.

Query with AND: Request Body JSON #

{
  "table":"asset",
  "query":[
    [
      {
        "searchFieldName":"Is_Cloud_Device",
        "operator":"==",
        "type":"Binary",
        "value":"Yes"
      }
    ],
    [
      {
        "searchFieldName":"OS",
        "operator":"==",
        "type":"String",
        "value":"Windows Server 2019"
      }
    ]
  ],
  "paging": {
    "page": 0,
    "recordsPerPage": 5
  }
}
  • Line 2. Define the table parameter. In this example, we will query the “asset” table

  • Line 3. Define the query parameter.

  • Line 6. the record must include the field name “Is_Cloud_Device”

  • Line 7. the “Is_Cloud_Device” field contains an exact match

  • Line 9. to the value “Yes”

  • Line 8. Is_Cloud_Device has a data type of String

  • Line 11. AND

  • Line 14. the record must include the field name “OS”

  • Line 15. the “OS” field contains an exact match

  • Line 17. to the value “Windows Server 2019”

  • Line 16. OS has a data type of String

  • Lines 21-24. Specify pagination

Query with AND: Response #

The response includes the entire asset record for each asset that matches both Is_Cloud_Device is “Yes” and OS is “Windows Server 2019”.

The response is over 2700 lines. Here is an abbreviated response:

{
"totalRecords": 230,
"data": [
{
"_id": "6461f102081577f5c85d8371",
"_time": 1684139969,
"run_time": 1684139969,
"Asset_Name": "I-ZOW1CU6BPI4VFX2WZ",
"Is_Public": null,
"Last_Discovered_Datetime": 1684133227,
"Services": [
"http"
],
"FQDN": [
"ip-172-30-90-37.us-west-1.compute.internal"
],
"app": [