Public API Query Builder

Enhanced JSON Configuration Documentation

This documentation provides detailed insights into the JSON configuration for querying data through a flexible API interface. The configuration incorporates filters, pagination, sorting, and date range specifications.

Global search across catalog.

POSThttps://app.configure8.io/public/v1/query-builder

Body

application/json

Filter properties

pageNumbernumber

Requested page, note that it starts with 0

pageSizenumber

Maximum entities in one paginated response

relationsarray of string

Relations to include

schemaIdentifier*string

Schema identifier to search against (Fetched from the UI)

filterarray of string

Filter properties

sortall of

Sort properties by field

startDatestring (date-time)

Example: "2021-01-01T00:00:00.000Z"

endDatestring (date-time)

Example: "2021-01-01T00:00:00.000Z"

Response

200400401403500

Body

application/json

items*array of array

Items found

totalFound*number

Total found items

Example: 1000

pageNumber*number

Requested page, note that it starts with 0

pageSize*number

Maximum entities in one paginated response

Request

JavaScriptCurlPython

const response = await fetch('https://app.configure8.io/public/v1/query-builder', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "schemaIdentifier": "text"
    }),
});
const data = await response.json();

Response

200

{
  "items": [
    []
  ],
  "totalFound": 1000,
  "pageNumber": 0,
  "pageSize": 0
}

Global term aggregated search across C8 catalog.

POSThttps://app.configure8.io/public/v1/query-builder/aggregated

Body

application/json

Aggregation properties

pageNumbernumber

Requested page, note that it starts with 0

pageSizenumber

Maximum entities in one paginated response

schemaIdentifier*string

Schema identifier to perform the aggregation on (Fetched from the UI)

aggregate*string

Aggregate to perform

Example: "count"

relationsarray of string

Group by fields

filterarray of string

Filter properties

sortall of

Sort properties by field

startDatestring (date-time)

Start date for the query

Example: "2021-01-01T00:00:00.000Z"

endDatestring (date-time)

End date for the query

Example: "2021-01-01T00:00:00.000Z"

Response

200400401403500

Body

application/json

items*array of QueryBuilderAggregation (object)

Aggregated items

totalFound*number

Total found items

Example: 1000

pageNumber*number

Requested page, note that it starts with 0

pageSize*number

Maximum entities in one paginated response

Request

JavaScriptCurlPython

const response = await fetch('https://app.configure8.io/public/v1/query-builder/aggregated', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "schemaIdentifier": "text",
      "aggregate": "count"
    }),
});
const data = await response.json();

Response

200

{
  "items": [
    {
      "count": 10
    }
  ],
  "totalFound": 1000,
  "pageNumber": 0,
  "pageSize": 0
}

Input Details

Below, we provide different definitions and the structure for submitting data requests, which include optional and required parameters for filtering, sorting, and pagination.

Pagination (Optional)

• Page Size (pageSize): Limits the number of records returned per response. Defaults to 10.

• Page Number (pageNumber): Specifies the page number to return, starting from 0 by default.

Filters

The filter section specifies conditions to filter the dataset based on multiple fields, including

• name

• provider

• providerAccountId

• accruedCosts

• priorPeriodCosts

• changeCosts

• providerResourceType

• location

• tags

• vulnerabilities.name

• owners.name

• services.name

• environments.name

Multiple comparison operators (eq, ne, in, nin, ilike) are used to refine the search criteria.

Schema Identifier (schemaIdentifier):

The required field identifies the schema used in the query. There are two main type of schemas:

Core schemas

Base schema name	Schema Identifier
Applications	schema-application
Base	schema-base
Costs	schema-cost
Environments	schema-environment
Libraries	schema-library
Manifests	schema-manifest
Owners	schema-owners
Persons	schema-person
Ranges	schema-range
Repositories	schema-repository
Resources	schema-resource
Scorecards	schema-scorecard
Scorecard Metrics	schema-scorecard-metric
Scorecard Metric Level	scorecard-metric-level
Scorecard Metric Results	schema-scorecard-metric-results
Services	schema-service
Teams	schema-team
Vulnerabilities	schema-vulnerabilities

User defined schemas

The other type for schemas are the ones that you created in your organization, you can find it from Settings -> Schemas

Relationships (Optional)

Relations (relations): Optional array specifying related data entities to include in the query results.

Sorting (Optional)

The sorting of query results can be controlled by specifying the field and direction of the sort.

• Field: The field on which to sort the results. (Default to name)

• Direction: The direction of the sort, either ASC (ascending) or DESC (descending). (Default to ASC)

Date Range (Optional)

• Start Date (startDate): Optional start date for filtering the data.

• End Date (endDate): Optional end date for filtering the data.

Filter Types

The filter can be specified using one or more conditions, which can be simple comparisons, logical AND, or logical OR operations.

Compare:

Defines a simple comparison filter. Specifies a comparison operation on a field.

• Field: The name of the field to filter on.

• Value: The value to compare against, which can be a single value, an array of values, or null.

• Compare: The type of comparison (e.g., eq, ne)

Or and And:

Both interfaces define a logical grouping of conditions:

• Type: Specifies whether the grouping is an AND or an OR operation.

• Conditions: An array of And , Or , and Compare objects defining nested filters.

Example search body

Example 1 - Get the list of repositories that don't have any services

Curl

curl --location 'https://app.configure8.io/public/v1/query-builder' \
--header 'api-key: c8ak_***' \
--header 'content-type: application/json' \
--data '{
    "filter": [
        {
            "conditions": [
                {
                    "compare": "eq",
                    "field": "services.name",
                    "type": "compare",
                    "value": null
                }
            ],
            "type": "and"
        }
    ],
    "schemaIdentifier": "schema-repository",
}'

NodeJs

const axios = require('axios');
let data = `{
    "filter": [
      "conditions": [
        {
          "compare": "eq",
          "field": "services.name",
          "type": "compare",
          "value": null
        }
      ],
      "type": "and"
    }
  ],
  "schemaIdentifier": "schema-repository"
}`;

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://app.configure8.io/public/v1/query-builder',
  headers: { 
    'api-key': 'c8ak_***', 
    'content-type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import requests
import json

url = "https://app.configure8.io/public/v1/query-builder"

payload = """{
  "filter": [
    {
      "conditions": [
        {
          "compare": "eq",
          "field": "services.name",
          "type": "compare",
          "value": null
        }
      ],
      "type": "and"
    }
  ],
  "schemaIdentifier": "schema-repository"
}"""

headers = {
  'api-key': 'c8ak_***',
  'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

You can swap the compare property with any of the following:

• ne

  • In this case, value property should be a single string or number, and the query builder will try to find all repositories whose related service's name is not equal to the provided value.

• in

  • In this case, value property should be an array, and the query builder will try to find all repositories that have services with names that are in the provided list.

• nin

  • This case works precisely in the opposite of the in operator.

• ilike

  • To have the ability to find repositories that we only know part of their service's name, you can take advantage of the ilike For the wildcard, you can use %.

for example '%test-name%'

Example 2 - Use And and Or in one query

With the power of query builder, it's also possible to combine two different conditions; for example, you want to find all repositories that either no services nor owners.

Curl

curl --location 'https://app.configure8.io/public/v1/query-builder' \
--header 'api-key: c8ak_***' \
--header 'content-type: application/json' \
--data '{
    "filter": [
        {
            "conditions": [
                {
                    "compare": "eq",
                    "field": "services.name",
                    "type": "compare",
                    "value": null
                },
                {
                    "compare": "eq",
                    "field": "owners.name",
                    "type": "compare",
                    "value": null
                }
            ],
            "type": "or"
        }
    ],
    "schemaIdentifier": "schema-repository",
}'

NodeJs

const axios = require('axios');
let data = `{
    "filter": [
      "conditions": [
        {
          "compare": "eq",
          "field": "services.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "eq",
          "field": "owners.name",
          "type": "compare",
          "value": null
        }
      ],
      "type": "or"
    }
  ],
  "schemaIdentifier": "schema-repository"
}`;

let config = {
  method: 'post',
  maxBodyLength: Infinity,
  url: 'https://app.configure8.io/public/v1/query-builder',
  headers: { 
    'api-key': 'c8ak_***', 
    'content-type': 'application/json'
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});

Python

import requests
import json

url = "https://app.configure8.io/public/v1/query-builder"

payload = """{
  "filter": [
    {
      "conditions": [
        {
          "compare": "eq",
          "field": "services.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "eq",
          "field": "owners.name",
          "type": "compare",
          "value": null
        }
      ],
      "type": "or"
    }
  ],
  "schemaIdentifier": "schema-repository"
}"""

headers = {
  'api-key': 'c8ak_***',
  'content-type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Full example

This is an illustrative, not functional, example. Its goal is to provide a large list of filter conditions so you can copy and adapt parts of it to your needs.

{
  "filter": [
    {
      "conditions": [
        {
          "compare": "eq",
          "field": "name",
          "type": "compare",
          "value": "ecr-pullthroughcache-github/aquasecurity/trivy-operator/<untagged>"
        },
        {
          "compare": "ne",
          "field": "name",
          "type": "compare",
          "value": "ecr-pullthroughcache-github/aquasecurity/trivy-operator/<untagged>"
        },
        {
          "compare": "in",
          "field": "name",
          "type": "compare",
          "value": [
            "ecr-pullthroughcache-github/aquasecurity/trivy-operator/<untagged>",
            "ecr-pullthroughcache-github/aquasecurity/trivy/<untagged>"
          ]
        },
        {
          "compare": "nin",
          "field": "name",
          "type": "compare",
          "value": [
            "ecr-pullthroughcache-github/aquasecurity/trivy-operator/<untagged>",
            "ecr-pullthroughcache-github/aquasecurity/trivy/<untagged>"
          ]
        },
        {
          "compare": "ilike",
          "field": "name",
          "type": "compare",
          "value": "%example contain%"
        },
        {
          "compare": "eq",
          "field": "name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "name",
          "type": "compare",
          "value": "example starts with%"
        },
        {
          "compare": "ilike",
          "field": "name",
          "type": "compare",
          "value": "%example ends with"
        },
        {
          "compare": "eq",
          "field": "provider",
          "type": "compare",
          "value": "AWS"
        },
        {
          "compare": "ne",
          "field": "provider",
          "type": "compare",
          "value": "K8s"
        },
        {
          "compare": "in",
          "field": "provider",
          "type": "compare",
          "value": [
            "AWS",
            "K8s"
          ]
        },
        {
          "compare": "nin",
          "field": "provider",
          "type": "compare",
          "value": [
            "AWS",
            "K8s"
          ]
        },
        {
          "compare": "ilike",
          "field": "provider",
          "type": "compare",
          "value": "%example containing%"
        },
        {
          "compare": "eq",
          "field": "provider",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "provider",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "provider",
          "type": "compare",
          "value": "example starts with%"
        },
        {
          "compare": "ilike",
          "field": "provider",
          "type": "compare",
          "value": "%example ends with"
        },
        {
          "compare": "eq",
          "field": "providerAccountId",
          "type": "compare",
          "value": "699577016021"
        },
        {
          "compare": "ne",
          "field": "providerAccountId",
          "type": "compare",
          "value": "699577016021"
        },
        {
          "compare": "in",
          "field": "providerAccountId",
          "type": "compare",
          "value": [
            "699577016021",
            "000443732842"
          ]
        },
        {
          "compare": "nin",
          "field": "providerAccountId",
          "type": "compare",
          "value": [
            "699577016021",
            "000443732842"
          ]
        },
        {
          "compare": "ilike",
          "field": "providerAccountId",
          "type": "compare",
          "value": "%1223%"
        },
        {
          "compare": "eq",
          "field": "providerAccountId",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "providerAccountId",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "providerAccountId",
          "type": "compare",
          "value": "123%"
        },
        {
          "compare": "ilike",
          "field": "providerAccountId",
          "type": "compare",
          "value": "%123"
        },
        {
          "compare": "eq",
          "field": "accruedCosts",
          "type": "compare",
          "value": -5
        },
        {
          "compare": "ne",
          "field": "accruedCosts",
          "type": "compare",
          "value": 6
        },
        {
          "compare": "lt",
          "field": "accruedCosts",
          "type": "compare",
          "value": 4
        },
        {
          "compare": "lge",
          "field": "accruedCosts",
          "type": "compare",
          "value": -2
        },
        {
          "compare": "gt",
          "field": "accruedCosts",
          "type": "compare",
          "value": -7
        },
        {
          "compare": "gte",
          "field": "accruedCosts",
          "type": "compare",
          "value": 2
        },
        {
          "compare": "eq",
          "field": "priorPeriodCosts",
          "type": "compare",
          "value": -5
        },
        {
          "compare": "ne",
          "field": "priorPeriodCosts",
          "type": "compare",
          "value": 6
        },
        {
          "compare": "lt",
          "field": "priorPeriodCosts",
          "type": "compare",
          "value": 4
        },
        {
          "compare": "lge",
          "field": "priorPeriodCosts",
          "type": "compare",
          "value": -2
        },
        {
          "compare": "gt",
          "field": "priorPeriodCosts",
          "type": "compare",
          "value": -7
        },
        {
          "compare": "gte",
          "field": "priorPeriodCosts",
          "type": "compare",
          "value": 2
        },
        {
          "compare": "eq",
          "field": "changeCosts",
          "type": "compare",
          "value": -5
        },
        {
          "compare": "ne",
          "field": "changeCosts",
          "type": "compare",
          "value": 6
        },
        {
          "compare": "lt",
          "field": "changeCosts",
          "type": "compare",
          "value": 4
        },
        {
          "compare": "lge",
          "field": "changeCosts",
          "type": "compare",
          "value": -2
        },
        {
          "compare": "gt",
          "field": "changeCosts",
          "type": "compare",
          "value": -7
        },
        {
          "compare": "gte",
          "field": "changeCosts",
          "type": "compare",
          "value": 2
        },
        {
          "compare": "eq",
          "field": "providerResourceType",
          "type": "compare",
          "value": "AWS:LAMBDA:Function"
        },
        {
          "compare": "ne",
          "field": "providerResourceType",
          "type": "compare",
          "value": "AWS:LAMBDA:Function"
        },
        {
          "compare": "in",
          "field": "providerResourceType",
          "type": "compare",
          "value": [
            "AWS:LAMBDA:Function",
            "AWS:ACM:Certificate"
          ]
        },
        {
          "compare": "nin",
          "field": "providerResourceType",
          "type": "compare",
          "value": [
            "AWS:LAMBDA:Function",
            "AWS:ACM:Certificate"
          ]
        },
        {
          "compare": "ilike",
          "field": "providerResourceType",
          "type": "compare",
          "value": "%:LAMBDA:%"
        },
        {
          "compare": "eq",
          "field": "providerResourceType",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "providerResourceType",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "providerResourceType",
          "type": "compare",
          "value": "AWS:LAMBDA:%"
        },
        {
          "compare": "ilike",
          "field": "providerResourceType",
          "type": "compare",
          "value": "%:LAMBDA:Function"
        },
        {
          "compare": "eq",
          "field": "location",
          "type": "compare",
          "value": "us-east-2"
        },
        {
          "compare": "ne",
          "field": "location",
          "type": "compare",
          "value": "us-east-2"
        },
        {
          "compare": "in",
          "field": "location",
          "type": "compare",
          "value": [
            "us-east-2",
            "us-east-1"
          ]
        },
        {
          "compare": "nin",
          "field": "location",
          "type": "compare",
          "value": [
            "us-east-2",
            "us-east-1"
          ]
        },
        {
          "compare": "ilike",
          "field": "location",
          "type": "compare",
          "value": "%-east-%"
        },
        {
          "compare": "eq",
          "field": "location",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "location",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "location",
          "type": "compare",
          "value": "us-%"
        },
        {
          "compare": "ilike",
          "field": "location",
          "type": "compare",
          "value": "%-east-1"
        },
        {
          "compare": "ilike",
          "field": "tags",
          "type": "compare",
          "value": "%{\"aws:cloudformation:logical-id\":\"Forwarder\",\"aws:cloudformation:stack-id\":\"arn:aws:cloudformation:us-east-1:699577016021:stack/datadog-ForwarderStack-1E2XI41ZNSVUC/1b0be1a0-5244-11ec-84a7-124b8f7e7c13\",\"aws:cloudformation:stack-name\":\"datadog-ForwarderStack-1E2XI41ZNSVUC\",\"dd_forwarder_version\":\"3.40.0\"}%"
        },
        {
          "compare": "ilike",
          "field": "tags",
          "type": "compare",
          "value": "%example contain%"
        },
        {
          "compare": "eq",
          "field": "tags",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "tags",
          "type": "compare",
          "value": null
        },
        {
          "compare": "eq",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": "Axios Cross-Site Request Forgery Vulnerability"
        },
        {
          "compare": "ne",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": "Axios Cross-Site Request Forgery Vulnerability"
        },
        {
          "compare": "in",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": [
            "Axios Cross-Site Request Forgery Vulnerability",
            "Inefficient Regular Expression Complexity in nth-check."
          ]
        },
        {
          "compare": "nin",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": [
            "Axios Cross-Site Request Forgery Vulnerability",
            "Inefficient Regular Expression Complexity in nth-check."
          ]
        },
        {
          "compare": "ilike",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": "%Cross%"
        },
        {
          "compare": "eq",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": "Axios-%"
        },
        {
          "compare": "ilike",
          "field": "vulnerabilities.name",
          "type": "compare",
          "value": "%check"
        },
        {
          "compare": "eq",
          "field": "owners.name",
          "type": "compare",
          "value": "John Doe"
        },
        {
          "compare": "ne",
          "field": "owners.name",
          "type": "compare",
          "value": "John Doe"
        },
        {
          "compare": "in",
          "field": "owners.name",
          "type": "compare",
          "value": [
            "John Doe",
            "Alice Doe"
          ]
        },
        {
          "compare": "nin",
          "field": "owners.name",
          "type": "compare",
          "value": [
            "John Doe",
            "Alice Doe"
          ]
        },
        {
          "compare": "ilike",
          "field": "owners.name",
          "type": "compare",
          "value": "%ohn%"
        },
        {
          "compare": "eq",
          "field": "owners.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "owners.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "owners.name",
          "type": "compare",
          "value": "John%"
        },
        {
          "compare": "ilike",
          "field": "owners.name",
          "type": "compare",
          "value": "%Doe"
        },
        {
          "compare": "eq",
          "field": "services.name",
          "type": "compare",
          "value": "Anomaly Telemetry Ingestion Service"
        },
        {
          "compare": "ne",
          "field": "services.name",
          "type": "compare",
          "value": "Anomaly Telemetry Ingestion Service"
        },
        {
          "compare": "in",
          "field": "services.name",
          "type": "compare",
          "value": [
            "Anomaly Telemetry Ingestion Service",
            "Automated Driving Service"
          ]
        },
        {
          "compare": "nin",
          "field": "services.name",
          "type": "compare",
          "value": [
            "Anomaly Telemetry Ingestion Service",
            "Automated Driving Service"
          ]
        },
        {
          "compare": "ilike",
          "field": "services.name",
          "type": "compare",
          "value": "%driving%"
        },
        {
          "compare": "eq",
          "field": "services.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "services.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "services.name",
          "type": "compare",
          "value": "Automated%"
        },
        {
          "compare": "ilike",
          "field": "services.name",
          "type": "compare",
          "value": "%Service"
        },
        {
          "compare": "eq",
          "field": "environments.name",
          "type": "compare",
          "value": "Pre-Production"
        },
        {
          "compare": "ne",
          "field": "environments.name",
          "type": "compare",
          "value": "Pre-Production"
        },
        {
          "compare": "in",
          "field": "environments.name",
          "type": "compare",
          "value": [
            "Pre-Production",
            "Quality Assurance"
          ]
        },
        {
          "compare": "nin",
          "field": "environments.name",
          "type": "compare",
          "value": [
            "Pre-Production",
            "Quality Assurance"
          ]
        },
        {
          "compare": "ilike",
          "field": "environments.name",
          "type": "compare",
          "value": "%Assur%"
        },
        {
          "compare": "eq",
          "field": "environments.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ne",
          "field": "environments.name",
          "type": "compare",
          "value": null
        },
        {
          "compare": "ilike",
          "field": "environments.name",
          "type": "compare",
          "value": "Quality%"
        },
        {
          "compare": "ilike",
          "field": "environments.name",
          "type": "compare",
          "value": "%Assurance"
        }
      ],
      "type": "and"
    }
  ],
  "pageSize": 25,
  "pageNumber": 0,
  "relations": [
    "vulnerabilities:count",
    "owners",
    "services:count",
    "environments:count"
  ],
  "schemaIdentifier": "sample-schema",
  "sort": {
    "direction": "DESC",
    "field": "accruedCosts"
  },
  "endDate": "2024-04-13T23:59:59.999Z",
  "startDate": "2024-04-07T00:00:00.000Z"
}