Endpoints for Assets and Users

You can use the Lucidum API to:

• Retrieve a list of available fields with a description and data type for each field

• Query Lucidum as you would from the Lucidum Query Builder, including using OR and AND statements

The following sections describe the endpoints for these actions.

Headers

Requests to the endpoints in the Lucidum API v2 must also include a header with:

• Content-Type of JSON.

• bearer Token we generated in the Edit User page.

Retrieve the List of Fields for Assets: /CMDB/v2/data/metadata/asset

The endpoint for querying 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.

The results return the same data as you see in the New Query page or Edit Query page when you click on the Field field.

See the examples chapter to see examples of the API request and the response.

Retrieve the List of Fields for Users: /CMDB/v2/data/metadata/user

The endpoint for querying the list of fields for users from the Lucidum database. The response includes the same list of fields for a user 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.

The results return the same data as you see in the New Query page or Edit Query page when you click on the Field field.

See the examples chapter to see examples of the API request and the response.

Query the Lucidum Database About Assets and Users: /CMDB/v2/data/cmdb

The endpoint for querying the Lucidum database, using fields, operators, AND statements, and OR statements, as you would in the Query Builder in the Lucidum UI.

Query Syntax

Because requests to the endpoint /CMDB/v2/data/cmdb use the POST method, we can include a request body. The request body with its query parameter looks like this:

{
  "table":"asset",
  "query":[
    [
      {
        "searchFieldName":"Asset_Type",
        "operator":"==",
        "type":"String",
        "value":"Servers"
      }
    ]
  ]
}

• Note that the body uses JSON syntax. For information on JSON syntax, see https://www.w3schools.com/js/js_json_syntax.asp

• Line 2. Define the table parameter. We will query the “asset” table in the Lucidum database

• Line 3. Define the query parameter.

• Line 6. The records to retrieve must include the field name “Asset_Type”

• Line 7. The “Asset_Type” field contains an exact match

• Line 9. to the value “Servers”

• Line 8. Asset_Type has a data type of String

Fields

Fields are one or more properties that you are interested in, such as “first time seen”, “ip address”, “county code”, or “risk score”. Fields map to column names in a database table.

Fields are characteristics of the Lucidum objects. For example, a characteristic of a User is the user’s email address. A characteristic of an asset is the asset’s IP address. Usually, a field maps to a column name in a Lucidum database.

To view a list of all fields for assets or all fields for users, you can use the endpoint /CMDB/v2/data/metadata/asset or /CMDB/v2/data/metadata/user.

In the query parameter, you use the syntax:

"searchFieldName":"<field name>",

where:

• searchFieldName. In the name: value pair for the field, the name string “searchFieldName” tells the API that the following value is a field name.

• <field name>. In the name: value pair for searchFieldName, the field name tells the API which field name to search for.

An example of the name:value pair for fields is:

"searchFieldName":"Asset_Type",

In this example, the Lucidum API will examine the field Asset_Type.

Note that the field name must match the case returned by /CMDB/v2/data/metadata/asset or /CMDB/v2/data/metadata/user. For example, “Asset_Type”, not “asset_type” nor “Asset Type”. And “sourcetype”, not “Sourcetype” nor “source type”

Datetime Fields

Datetime fields where the operator is:

• within past

• not within past

• within future

• not within future

require a specific syntax.

{
  "table":"asset",
  "query":[
    [
      {
        "searchFieldName":"First_Time_Seen",
        "operator":"within past",
        "type":"Datetime",
        "value":"1, month"
      }
    ]
  ]
}

Note that the “value” is “1, month”.

This matches the two fields in the query builder, where you specify an integer and a range.

Dynamic Fields

You can include dynamic fields in API queries. Specify the field name as it appears in the Query Builder.

Custom Fields

To include a custom field in an API query, specify the field name as it appear in the Query Builder.

Custom fields appear in the category of Customer Fields or Custom Fields in the Query Builder. The field names looks like:

[Custom] <field name>

Operators

Operators define the relationship between the fields and the values. Operators can include “match”, “not match”, “is equal to”, “is not equal to”, “is greater than”, “is less than”, “exists”, “is empty”, among others. Lucidum provides a set of operators for each field. For details on operators, see the chapter on Operators and Data Types.

In the query parameter, you use the syntax:

"operator":"<operator name>",

where:

• operator. In the name: value pair for operator, the name string “operator” tells the API that the following value is an operator.

• <operator name>. In the name: value pair for operators, the operator name tells the API which operator to use during the search and filter.

And example of an operator is:

"operator":"==",

In this example, the Lucidum API will look for an exact match (is equal to).

Note that the operators “==”, “!=”, “in”, and “not in” are case sensitive. The results will match the case of the Value string.

Data Type

The data type describes the field and its value. Data type determines the operators to use with the field.

To view a list of all fields for assets and their data types or all fields for users and their data types, you can use the endpoint /CMDB/v2/data/metadata/asset or /CMDB/v2/data/metadata/user.

For details on data types and their operators, see the chapter on Operators and Data Types.

In the query parameter, you use the syntax:

"type":"<data type>",

where:

• type. In the name: value pair for data type, the name string “type” tells the API that the following value is a data type.

• <data type>. In the name: value pair for data type, the data type tells the API which data type to expect during the search. Choices are:

  • Binary

  • Datetime

  • Float

  • Integer

  • List

  • String

Note that the data type must be specified with Initial capital letter in the query. For example, “String”, not “string”.

"type":"String",

In this example, the Lucidum API will search for a string.

Values

Values define the criteria for the specified fields. For example, if you chose “Memory Size (GB)” as a field, you could choose “is equal to” as an operator and “256” as a value. Your results would include only assets with 256 GB of memory.

To view a list of all values for asset fields or all values for user fieldss, you can use the endpoint /CMDB/v2/data/metadata/asset or /CMDB/v2/data/metadata/user.

In the query parameter, you use the syntax:

"value": "<value to match>"

where:

• value. In the name: value pair for value, the name string “value” tells the API that the following value is a value.

• <operator name>. In the name: value pair for value, the value to match tells the API which value to search for during the query.

And example of an operator is:

"value":"Servers",

In this example, the Lucidum API will look for the value “Servers”

Example Query

If we put together the parts from the previous sections, the query looks like this:

{
  "table":"asset",
  "query":[
    [
      {
        "searchFieldName":"Asset_Type",
        "operator":"==",
        "type":"String",
        "value":"Servers"
      }
    ]
  ]
}

• Note that the body uses JSON syntax. For information on JSON syntax, see https://www.w3schools.com/js/js_json_syntax.asp

• Line 2. Define the table parameter. We will query the “asset” table in the Lucidum database

• Line 3. Define the query parameter

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

• Line 7. The “Asset_Type” field contains an exact match

• Line 9. to the value “Servers”

• Line 8. Asset_Type has a data type of String

Using 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.

{
  "table":"asset",
  "query":[
    [
      {
        "searchFieldName":"Asset_Type",
        "operator":"==",
        "type":"String",
        "value":"Servers"
      }      
    ], 
    [
      {
        "searchFieldName":"Location_Country_ISO_Code",
        "operator":"==",
        "type":"String",
        "value":"US"
      }
    ]
  ],
  "paging": {
    "page": 0,     // 0 index paging
    "recordsPerPage": 5 // default page size is 20, max is 100, if greater than 100 default to 100, if less than equals to 0 default to 20
  }
}

In this example, notice the open square bracket after “query” (line 3) and the close square bracket above “paging” (line 20). These brackets enclose the entire query and are standard syntax for Lucidum API v2. The AND statement is expressed by the square brackets within the query (line 4, line 11, line 12, and line 19).

In this example, notice the text “],” on line 11. This internal close bracket followed by a comma signifies that the next set of square brackets surrounds the second part of an AND statement.

In this example:

• Note that the body uses JSON syntax. For information on JSON syntax, see https://www.w3schools.com/js/js_json_syntax.asp

• Line 2. Define the table parameter. We will query the “asset” table in the Lucidum database

• Line 3. Define the query parameter

• Line 6. the query should search for records that include the field name “Asset_Type”

• Line 7. the “Asset_Type” field must contain an exact match

• Line 9. to the value “Servers”

• Line 8. Asset_Type has a data type of String

• Line 11. AND

• Line 14. the query should search for records that includes the field name “Location_Country_ISO_Code”

• Line 15. the “Location_Country_ISO_Code” field must contain an exact match

• Line 17. to the value “US”

• Line 16. “Location_Country_ISO_Code” has a data type of String

• Line 21-24. Pagination

The results of this query will include records where Asset Type is “Servers” and Location Country ISO Code is “US”. All results must match both criteria.

Using OR

OR means that the results must meet one of the criteria in a multi-part query.

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

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

{
    "table": "asset", // 4 tables: asset, user, asset_history, user_history
    "query": [
        [
            {
                "searchFieldName": "Asset_Type",
                "operator": "==",
                "type": "String",
                "value": "Servers"
            },
            {
                "searchFieldName": "Asset_Type",
                "operator": "==",
                "type": "String",
                "value": "VM"
            }
        ]
    ]
}

The OR statement is expressed by the curly brackets within the query (line 5, line 10, line 11, and line 16).

In this example, notice the text “},” on line 10. This internal close bracket followed by a comma signifies that the next set of curly brackets surrounds the second part of an OR statement.

In this example:

• Note that the body uses JSON syntax. For information on JSON syntax, see https://www.w3schools.com/js/js_json_syntax.asp

• Line 2. Define the table parameter. We will query the “asset” table in the Lucidum database

• Line 3. Define the query parameter

• Line 6. The query should search for records that include the field name “Asset_Type”

• Line 7. the “Asset_Type” field must contain an exact match

• Line 9. to the value “Servers”

• Line 8. Asset_Type has a data type of String

• Line 10. OR

• Line 12. the query should search for records that includes the field name “Asset_Type”

• Line 13. the “Asset_Type” field must contain an exact match

• Line 15. to the value “VM”

• Line 14. Asset_Type has a data type of String

The results of this query will include both records where the asset type is “Servers” and records where the asset type is “VM”.

Pagination

The Lucidum APIs can return multiple pages in a response. Lucidum recommends that you specify a page to return and the number of records to include in the page.