CB LiveOps REST API

Version: v1

Introduction

CB LiveOps is a real-time query and remediation solution that gives teams faster, easier access to audit and change the system state of endpoints across their organization.

CB LiveOps contains two components; Live Response and Live Query. This document refers to the Live Query REST API.

Note: For returning users, three sub-fields inside device_filter named: device_ids, policy_ids, and device_types, have been deprecated in favor of device_id, policy_id, and os, respectively.

For API authentication information, view our Carbon Black Cloud Authentication Guide.

Common Headers/Parameters

Most API routes require all three headers, however, there are exceptions.

  1. X-Auth-Token: required in the request header. This is your authentication token.
  2. Content-Type: application/json
  3. org_key: required in the API path. This is your Carbon Black Cloud Org Key, you can view it under Settings > API Keys.

Start Query Run

Initiate a new Live Query search.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage CREATE

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs

Body 

{
    "sql": "<string>",
    "device_filter": {
        "device_id": [
            "<long>",
            "<long>"
        ],
        "os": [
            "<string>",
            "<string>"
        ],
        "policy_id": [
            "<long>",
            "<long>"
        ]
    },
    "name": "<string>",
    "notify_on_finish": "<boolean>",
    "schedule": {
        "cancellation_time": "<string>",
        "cancelled_by": "<string>",
        "next_run_time": "<string>",
        "previous_run_time": "<string>",
        "recurrence": "<string>",
        "rrule": "<string>",
        "status": "<string>",
        "timezone": "<string>"
    }
}

Response

Code Description Content-Type Content
201 Successfully added a Live Query run application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy. This field and sub-filters are optional and by default, it will run on all devices. All Devices No
device_filter.device_id A list of device IDs to filter on All Devices IDs No
device_filter.os A list of operating systems to filter on
Allowed Values: [ WINDOWS, MAC, LINUX]		 All Operating Systems No
device_filter.policy_id A list of policy IDs to filter on All Policies No
name Name for your Live Query Run SQL statement defined under field sql No
notify_on_finish Receive an email notification when query is completed false No
sql SQL for the Live Query Run N/A Yes

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs

Body 

{
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "name": "string",
  "notify_on_finish": true,
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string"
}

Response 

{
  "active_org_devices": 0,
  "archive_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "archived_by": "string",
  "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "cancelled_by": "string",
  "cancelled_count": 0,
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "error_count": 0,
  "id": "string",
  "in_progress_count": 0,
  "last_result_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "match_count": 0,
  "name": "string",
  "no_match_count": 0,
  "not_started_count": 0,
  "not_supported_count": 0,
  "notify_on_finish": true,
  "org_key": "string",
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "status": "ACTIVE",
  "status_update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "success_count": 0,
  "template_id": "string",
  "timeout_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "total_results": 0
}

Get Query Details

Returns the current details of a Live Query run. Users will be able to observe numerous metadata fields, such as status within the JSON response.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

GET <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}

Response

Code Description Content-Type Content
200 Successful retrieval of Live Query details application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Resource does not exist N/A N/A

Field status options:

  • ACTIVE: currently running.
  • TIMED_OUT: query timed out.
  • COMPLETE: query completed.
  • CANCELLED: user cancelled the Live Query run.

Example

Request

GET https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/erzo7cotkasdfghjk707srcjwnjgfmiv

Response 

{
  "active_org_devices": 0,
  "archive_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "archived_by": "string",
  "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "cancelled_by": "string",
  "cancelled_count": 0,
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "error_count": 0,
  "id": "string",
  "in_progress_count": 0,
  "last_result_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "match_count": 0,
  "name": "string",
  "no_match_count": 0,
  "not_started_count": 0,
  "not_supported_count": 0,
  "notify_on_finish": true,
  "org_key": "string",
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "status": "ACTIVE",
  "status_update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "success_count": 0,
  "template_id": "string",
  "timeout_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "total_results": 0
}

Get Query Run Results

Gets results from a Live Query run. The Live Query results can also be exported as a CSV compressed in a ZIP.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_search

Body 

{
    "criteria": {
        "device.id": [
            "<integer>",
            "<integer>"
        ],
        "device.name": [
            "<string>",
            "<string>"
        ],
        "device.os": [
            "<string>",
            "<string>"
        ],
        "device.policy_id": [
            "<integer>",
            "<integer>"
        ],
        "device.policy_name": [
            "<string>",
            "<string>"
        ],
        "status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>"
}

Response

Code Description Content-Type Content
200 Successfully retrieved Live Query results application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not Found N/A N/A

Request Body Schema

Field Description Default Required
criteria A Live Query Criteria. Note that beyond the listed properties in this schema, you can also filter on dynamic fields using this object. A dynamic field would be a column name you’d expect to be returned as part of your Live Query run. For example, if you create a run that targets the users table, a dynamic field on this criteria could be username or any other column outlined in the osQuery schema. N/A No
criteria.device_id List of device IDs to filter on All Devices No
criteria.device_name List of device names to filter on All Devices No
query A query to perform as part of the results search. Supports Apache Lucene syntax N/A No
rows For pagination, how many results to return N/A No
start For pagination, where to start retrieving results from 0 No
sort field: SQL Response Column
order: [ASC or DESC]		 N/A No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/erzo7cotkasdfghjk707srcjwnjgfmiv/results/_search

Body 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "device": {
        "id": 0,
        "name": "string",
        "os": "WINDOWS",
        "policy_id": 0,
        "policy_name": "string"
      },
      "device_message": "string",
      "fields": {},
      "id": "string",
      "status": "not_started",
      "time_received": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Get Live Query Recommendations

Get TauTin Live Query Recommendations.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage GET

Request

GET <psc-hostname>/livequery/v1/orgs/{org_key}/runs/recommendations

Responses

Code Description Content-Type Content
200 Successful retrieval of recommended queries application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Resource does not exist N/A N/A

Example

Request

GET https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/recommendations

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "link": "string",
      "queries": {
        "description": "string",
        "interval": 0,
        "query": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "results": "string",
        "supported_platforms": [
          "string"
        ],
        "title": "string"
      },
      "type": "string"
    }
  ]
}

Stop Query Run

Stop a running Live Query Run by changing its status to CANCELLED. Note that once a Run has been stopped it cannot be set back to ACTIVE.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage UPDATE

Request

PUT <psc-hostname>/livequery/orgs/{org_key}/runs/{id}/status

Request Body 

{
    "status": "<string>"
}

Responses

Code Description Content-Type Content
204 Successfully stopped a Live Query run N/A N/A
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Resource does not exist N/A N/A

Request Body Schema

Field Description Default Required
status Status to apply to the query CANCELLED Yes

Example

Request

PUT https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8/status

Body

{
    "status": "CANCELLED"
}

Response 

{}

Delete Query Run

Delete a Live Query Run.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage DELETE

Request

DELETE <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}

Responses

Code Description Content-Type Content
204 Successful deletion of a Live Query run N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Example

Request

DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/nnk1idf2xz3cit8unv3usfwyzmdqj8

Response 

{}

Get Facets From Live Query Results

Retrieve facets for Live Query results.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/_facet

Body 

  
{
    "criteria": {
        "device.id": [
            "<integer>",
            "<integer>"
        ],
        "device.name": [
            "<string>",
            "<string>"
        ],
        "device.os": [
            "<string>",
            "<string>"
        ],
        "device.policy_id": [
            "<integer>",
            "<integer>"
        ],
        "device.policy_name": [
            "<string>",
            "<string>"
        ],
        "status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>",
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": "<integer>"
    }
}

Response

Code Description Content-Type Content
200 Successfully retrieved query run facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
terms.fields Facet terms to retrieve N/A Yes
terms.rows Number of rows to retrieve per facet search result 20 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/_facet

Body 

  
{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0,
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

{
  "terms": [
    {
      "field": "string",
      "values": [
        {
          "id": "string",
          "name": "string",
          "total": 0
        }
      ]
    }
  ]
}

Get Device Summary Facets

Get facets for device summaries.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_facet

Body 

{
    "criteria": {
        "device.id": [
            "<long>",
            "<long>"
        ],
        "device.name": [
            "<string>",
            "<string>"
        ],
        "device.os": [
            "<string>",
            "<string>"
        ],
        "device.policy_id": [
            "<long>",
            "<long>"
        ],
        "device.policy_name": [
            "<string>",
            "<string>"
        ],
        "error_description": [
            "<string>",
            "<string>"
        ],
        "status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>",
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": "<integer>"
    }
}

Code Description Content-Type Content
200 Successfully retrieved Live Query device summary facets application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 No Live Query run found for the specified id N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
terms.fields Device summary fields to filter results on N/A Yes
terms.rows Number of rows to retrieve per facet search result 20 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/device_summaries/_facet

Body 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "error_description": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0,
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

{
  "terms": [
    {
      "field": "string",
      "values": [
        {
          "id": "string",
          "name": "string",
          "total": 0
        }
      ]
    }
  ]
}

Get Device Summary From Results

Get device summaries from the results of a Live Query run.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/{id}/results/device_summaries/_search

Body 

{
    "criteria": {
        "device.id": [
            "<long>",
            "<long>"
        ],
        "device.name": [
            "<string>",
            "<string>"
        ],
        "device.os": [
            "<string>",
            "<string>"
        ],
        "device.policy_id": [
            "<long>",
            "<long>"
        ],
        "device.policy_name": [
            "<string>",
            "<string>"
        ],
        "error_description": [
            "<string>",
            "<string>"
        ],
        "status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>"
}

Code Description Content-Type Content
200 Successfully retrieved Live Query device summaries application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 No Live Query run found for the specified id N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/tfbh5zdtbz16banjkygnodidgk5dxmqt/results/device_summaries/_facet

Body 

{
  "criteria": {
    "device.id": [
      0
    ],
    "device.name": [
      "string"
    ],
    "device.os": [
      "WINDOWS",
      "MAC",
      "LINUX"
    ],
    "device.policy_id": [
      0
    ],
    "device.policy_name": [
      "string"
    ],
    "error_description": [
      "string"
    ],
    "status": [
      "not_started"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "device": {
        "id": 0,
        "name": "string",
        "os": "WINDOWS",
        "policy_id": 0,
        "policy_name": "string"
      },
      "error_description": "string",
      "finish_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "metrics": {
        "additionalProp1": 0,
        "additionalProp2": 0,
        "additionalProp3": 0
      },
      "start_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "status": "not_started",
      "total_results": 0,
      "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Get Query History

Get and search for Live Query runs.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/runs/_search

Body 

{
    "criteria": {
        "recommended_query_id": [
            "<string>",
            "<string>"
        ],
        "schedule.status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>"
}

Responses

Code Description Content-Type Content
200 Successfully retrieved query runs application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
rows For paging, how many runs to return 20 No
sort.field Field to sort results on N/A No
sort.order Return runs in ascending (ASC) or descending (DESC) order. ASC No
start For paging, where to start retrieving runs from 0 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/runs/_search

Body 

{
  "criteria": {
    "recommended_query_id": [
      "string"
    ],
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "active_org_devices",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "created_by": "string",
      "device_filter": {
        "device_id": [
          0
        ],
        "os": [
          "WINDOWS"
        ],
        "policy_id": [
          0
        ]
      },
      "id": "string",
      "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "name": "string",
      "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "notify_on_finish": true,
      "recommended_query_id": "string",
      "schedule": {
        "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "cancelled_by": "string",
        "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "recurrence": "DAILY",
        "rrule": "string",
        "status": "ACTIVE",
        "timezone": "America/New_York"
      },
      "sql": "string",
      "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Create Live Query Template

Creating a Live Query Template.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage CREATE

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/templates

Body 

{
    "sql": "<string>",
    "device_filter": {
      "device_id": [
          "<long>",
          "<long>"
      ],
      "os": [
          "<string>",
          "<string>"
      ],
      "policy_id": [
          "<long>",
          "<long>"
      ]
    },
    "name": "<string>",
    "notify_on_finish": "<boolean>",
    "schedule": {
        "cancellation_time": "<string>",
        "cancelled_by": "<string>",
        "next_run_time": "<string>",
        "previous_run_time": "<string>",
        "recurrence": "<string>",
        "rrule": "<string>",
        "status": "<string>",
        "timezone": "<string>"
    }
}

Code Description Content-Type Content
201 Successfully created Live Query template application/json View example response below
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 No Live Query run found for the specified id N/A N/A

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy. This field and sub-filters are optional and by default, it will run on all devices. All Devices No
device_filter.device_id A list of device IDs to filter on All Devices IDs No
device_filter.os A list of operating systems to filter on
Allowed Values: [ WINDOWS, MAC, LINUX]		 All Operating Systems No
device_filter.policy_id A list of policy IDs to filter on All Policies No
name Name for your Live Query Run SQL statement defined under field sql No
notify_on_finish Receive an email notification when query is completed false No
sql SQL for the Live Query Run N/A Yes

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates

Body 

{
  "sql": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "name": "string",
  "notify_on_finish": true,
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  }
}

Response 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Retrieve Facets Live Query Templates

Retrieve facets for Live Query Templates.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/templates/_facet

Body 

{
    "criteria": {
        "recommended_query_id": [
            "<string>",
            "<string>"
        ],
        "schedule.status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>",
    "terms": {
        "fields": [
            "<string>",
            "<string>"
        ],
        "rows": "<integer>"
    }
}

Code Description Content-Type Content
200 Successfully retrieved facet values application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No
terms.fields Device summary fields to filter results on N/A Yes
terms.rows Number of rows to retrieve per facet search result 20 No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/_facet

Body 

{
  "criteria": {
    "recommended_query_id": [
      "string"
    ],
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0,
  "terms": {
    "fields": [
      "string"
    ],
    "rows": 0
  }
}

Response 

{

}

Search Live Query Templates

Get and search for Live Query templates.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

POST <psc-hostname>/livequery/v1/orgs/{org_key}/templates/_search

Body 

{
    "criteria": {
        "recommended_query_id": [
            "<string>",
            "<string>"
        ],
        "schedule.status": [
            "<string>",
            "<string>"
        ]
    },
    "query": "<string>",
    "rows": "<integer>",
    "sort": [
        {
            "field": "<string>",
            "order": "<string>"
        },
        {
            "field": "<string>",
            "order": "<string>"
        }
    ],
    "start": "<integer>"
}

Code Description Content-Type Content
200 Successfully retrieved Live Query templates, sorted by create_time descending by default application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
criteria.additionalProperties Map of criteria filter to get facets for N/A No
query Free text search that supports case insensitive value queries. Requires whole word values. N/A No

Example

Request

POST https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/_search

Body 

{
  "criteria": {
    "recommended_query_id": [
      "string"
    ],
    "schedule.status": [
      "ACTIVE"
    ]
  },
  "query": "string",
  "rows": 0,
  "sort": [
    {
      "field": "string",
      "order": "ASC"
    }
  ],
  "start": 0
}

Response 

{
  "num_found": 0,
  "org_key": "string",
  "results": [
    {
      "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "created_by": "string",
      "device_filter": {
        "device_id": [
          0
        ],
        "os": [
          "WINDOWS"
        ],
        "policy_id": [
          0
        ]
      },
      "id": "string",
      "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "name": "string",
      "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
      "notify_on_finish": true,
      "recommended_query_id": "string",
      "schedule": {
        "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "cancelled_by": "string",
        "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
        "recurrence": "DAILY",
        "rrule": "string",
        "status": "ACTIVE",
        "timezone": "America/New_York"
      },
      "sql": "string",
      "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
    }
  ]
}

Retrieve Live Query Template by ID

Retrieve a Live Query template (i.e. run schedule) by template id.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage READ

Request

GET <psc-hostname>/livequery/v1/orgs/{org_key}/templates/{template_id}
Code Description Content-Type Content
200 Successfully retrieved a Live Query template application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Example

Request

GET https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/erzo7cotkasdfghjk707srcjwnjgfmiv

Response 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Edit Live Query Template by ID

Edit a query template (i.e. run schedule).

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage UPDATE

Request

PUT <psc-hostname>/livequery/v1/orgs/{org_key}/templates/{template_id}

Body 

{
    "create_time": "<string>",
    "created_by": "<string>",
    "device_filter": {
      "device_id": [
          "<long>",
          "<long>"
      ],
      "os": [
          "<string>",
          "<string>"
      ],
      "policy_id": [
          "<long>",
          "<long>"
      ]
    },
    "id": "<string>",
    "last_run_create_time": "<string>",
    "name": "<string>",
    "next_run_time": "<string>",
    "notify_on_finish": "<boolean>",
    "recommended_query_id": "<string>",
    "schedule": {
        "cancellation_time": "<string>",
        "cancelled_by": "<string>",
        "next_run_time": "<string>",
        "previous_run_time": "<string>",
        "recurrence": "<string>",
        "rrule": "<string>",
        "status": "<string>",
        "timezone": "<string>"
    },
    "sql": "<string>",
    "update_time": "<string>"
}

Code Description Content-Type Content
200 Successfully updated Live Query template application/json View example response below
400 The JSON body was malformed, or some part of the JSON body included an invalid value N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Request Body Schema

Field Description Default Required
device_filter Contains 3 sub-filters: device_id, os, policy. This field and sub-filters are optional and by default, it will run on all devices. All Devices No
device_filter.device_id A list of device IDs to filter on All Devices IDs No
device_filter.os A list of operating systems to filter on
Allowed Values: [ WINDOWS, MAC, LINUX]		 All Operating Systems No
device_filter.policy_id A list of policy IDs to filter on All Policies No
name Name for your Live Query Run SQL statement defined under field sql No
notify_on_finish Receive an email notification when query is completed false No
sql SQL for the Live Query Run N/A Yes

Example

Request

PUT https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/erzo7cotkasdfghjk707srcjwnjgfmiv

Body 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Response 

{
  "create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "created_by": "string",
  "device_filter": {
    "device_id": [
      0
    ],
    "os": [
      "WINDOWS"
    ],
    "policy_id": [
      0
    ]
  },
  "id": "string",
  "last_run_create_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "name": "string",
  "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
  "notify_on_finish": true,
  "recommended_query_id": "string",
  "schedule": {
    "cancellation_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "cancelled_by": "string",
    "next_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "previous_run_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'",
    "recurrence": "DAILY",
    "rrule": "string",
    "status": "ACTIVE",
    "timezone": "America/New_York"
  },
  "sql": "string",
  "update_time": "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"
}

Delete Query Schedule by ID

Delete a query schedule by id.

RBAC Permissions Required

Permission (.notation name) Operation(s)
livequery.manage DELETE

Request

DELETE <psc-hostname>/livequery/v1/orgs/{org_key}/templates/{template_id}

Responses

Code Description Content-Type Content
204 Successfully deleted a query schedule N/A N/A
401 Unauthorized N/A N/A
403 Forbidden N/A N/A
404 Not found N/A N/A

Example

Request

DELETE https://defense.conferdeploy.net/livequery/v1/orgs/ASDF12A/templates/erzo7cotkasdfghjk707srcjwnjgfmiv

Response 

{}

Last modified on January 9, 2020