openapi: 3.0.0 info: title: XDR Query API description: >- This is the OAS 3.0 specification for the XDR Query API in Sophos Central. See [https://developer.sophos.com/getting-started-with-xdr-query](https://developer.sophos.com/getting-started-with-xdr-query). version: 1.3.0 contact: name: Sophos Central APIs email: apis@sophos.com url: 'https://developer.sophos.com' tags: - name: Category description: Maintain query categories. - name: Query description: Maintain queries. - name: Runs description: Run queries against the Sophos Data Lake. servers: - url: 'https://api-{dataRegion}.central.sophos.com/xdr-query/v1' description: Regional service in the production environment. variables: dataRegion: description: Data region where the service is. default: eu01 enum: - eu01 - eu02 - us01 - us03 - ca01 - au01 - jp01 - in01 - br01 - ae01 security: - bearerAuth: [] paths: /queries/runs: get: x-soph-permissions: 'xdr.query:read' summary: List query runs description: Get the list of query runs matching the given filters. operationId: getQueryRuns tags: - Runs parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: false schema: type: string format: uuid - name: statuses in: query description: Query run statuses. required: false schema: type: array items: type: string description: Status of a query run. enum: - started - pending - finished - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - name: order in: query description: Order of results for a query run. required: false schema: type: string description: Order direction. enum: - asc - desc responses: '200': description: Page of query runs. content: application/json: schema: type: object properties: items: description: Page of query runs. type: array items: description: Single instance of a query run. type: object required: - id - createdAt - status - result properties: id: description: Query run ID. type: string createdAt: description: When the query run was started. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization expiresAt: description: When the query run expires or expired. type: string format: datetime finishedAt: description: When the query run completed. type: string format: datetime result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - canceled - timedOut status: type: string description: Status of a query run. enum: - started - pending - finished name: description: Query name. type: string query: description: Reference to a query. type: object required: - id properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: Identifier for query name. type: string category: description: Reference to a query category. type: object required: - id properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for 'canned' categories. type: string template: description: Query SQL template. type: string variables: description: Query template replacement variables. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: >- Data types supported for EDR Data Lake queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: The meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url matchEndpoints: type: object description: Criteria to select endpoints. required: - filters properties: filters: description: >- Filters to select specific endpoints. Currently, only filtering by endpoint IDs is supported, and it must be supplied. type: array items: type: object description: Find endpoints matching criteria. properties: ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid minItems: 1 maxItems: 1 from: type: string format: date-time description: >- Start of time range that was applied when the query was run. example: '2021-10-01T00:00:00.000Z' to: type: string format: date-time description: >- End of time range that was applied when the query was run. example: '2021-10-02T00:00:00.000Z' pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri post: x-soph-permissions: 'xdr.query:execute' summary: Run query description: >- Run a query against the Sophos Data Lake, passing the SQL code as the value of a field in the request JSON. The schema reference is available [here](https://docs.sophos.com/central/References/schemas/index.html?schema=xdr_schema_docs). operationId: startQueryRun tags: - Runs parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: false schema: type: string format: uuid requestBody: required: true description: Query run request. content: application/json: schema: description: Request to start a query run. type: object properties: savedQuery: type: object description: >- A saved query to run. Required if an ad hoc query isn't supplied. required: - queryId properties: categoryId: description: (Optional) Query category ID. type: string format: uuid queryId: description: Saved query ID. type: string format: uuid adHocQuery: type: object description: >- Ad hoc query to run. Required if a saved query isn't supplied. required: - template properties: name: description: (Optional) Name for the ad hoc query. type: string minLength: 1 maxLength: 300 template: description: >- SQL statement for the query. This can contain replacement variables wrapped in `$$` (double dollar sign) delimiters. example: >- select pid, cmdline, sha256 from xdr_data where parent_name = '$$proc_name$$' and query_name = 'running_processes_windows_sophos' type: string minLength: 15 maxLength: 50000 variables: description: Values of variables to be replaced in the template SQL. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for EDR Data Lake queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: The meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url matchEndpoints: type: object description: Criteria to select endpoints. required: - filters properties: filters: description: >- Filters to select specific endpoints. Currently, only filtering by endpoint IDs is supported, and it must be supplied. type: array items: type: object description: Find endpoints matching criteria. properties: ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid minItems: 1 maxItems: 1 from: type: string description: >- Start of time range that is applied when running the query (inclusive). It can be in ISO duration format, full UTC timestamp or date only. maxLength: 24 example: FullUtcTimestamp: value: '2022-01-21T12:02:01.700Z' DateOnly: value: '2022-01-21T00:00:00.000Z' Duration: value: '-P7D' summary: 7 days ago to: type: string description: >- End of time range that is applied when running the query (inclusive). It can be in ISO duration format, full UTC timestamp or date only. maxLength: 24 example: FullUtcTimestamp: value: '2022-01-21T12:02:01.700Z' DateOnly: value: '2022-01-21T00:00:00.000Z' Duration: value: '-P7D' summary: 7 days ago example: adHocQuery: template: select * from "xdr_data" limit 10 from: '2022-01-01T12:02:01.000Z' to: '2022-01-21T12:02:01.700Z' responses: '201': description: Query run created. content: application/json: schema: description: Single instance of a query run. type: object required: - id - createdAt - status - result properties: id: description: Query run ID. type: string createdAt: description: When the query run was started. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization expiresAt: description: When the query run expires or expired. type: string format: datetime finishedAt: description: When the query run completed. type: string format: datetime result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - canceled - timedOut status: type: string description: Status of a query run. enum: - started - pending - finished name: description: Query name. type: string query: description: Reference to a query. type: object required: - id properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: Identifier for query name. type: string category: description: Reference to a query category. type: object required: - id properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for 'canned' categories. type: string template: description: Query SQL template. type: string variables: description: Query template replacement variables. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for EDR Data Lake queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: The meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url matchEndpoints: type: object description: Criteria to select endpoints. required: - filters properties: filters: description: >- Filters to select specific endpoints. Currently, only filtering by endpoint IDs is supported, and it must be supplied. type: array items: type: object description: Find endpoints matching criteria. properties: ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid minItems: 1 maxItems: 1 from: type: string format: date-time description: >- Start of time range that was applied when the query was run. example: '2021-10-01T00:00:00.000Z' to: type: string format: date-time description: End of time range that was applied when the query was run. example: '2021-10-02T00:00:00.000Z' '400': description: Bad request. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/queries/runs/{runId}': get: x-soph-permissions: 'xdr.query:read' summary: Get query run description: Get a query run by ID. operationId: getQueryRun tags: - Runs parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: false schema: type: string format: uuid - name: runId in: path description: Query run ID. required: true schema: type: string format: uuid responses: '200': description: Query run found. content: application/json: schema: description: Single instance of a query run. type: object required: - id - createdAt - status - result properties: id: description: Query run ID. type: string createdAt: description: When the query run was started. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization expiresAt: description: When the query run expires or expired. type: string format: datetime finishedAt: description: When the query run completed. type: string format: datetime result: type: string description: Overall result of a query run. enum: - notAvailable - succeeded - failed - canceled - timedOut status: type: string description: Status of a query run. enum: - started - pending - finished name: description: Query name. type: string query: description: Reference to a query. type: object required: - id properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: Identifier for query name. type: string category: description: Reference to a query category. type: object required: - id properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for 'canned' categories. type: string template: description: Query SQL template. type: string variables: description: Query template replacement variables. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for EDR Data Lake queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: The meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url matchEndpoints: type: object description: Criteria to select endpoints. required: - filters properties: filters: description: >- Filters to select specific endpoints. Currently, only filtering by endpoint IDs is supported, and it must be supplied. type: array items: type: object description: Find endpoints matching criteria. properties: ids: description: Find endpoints with the specified IDs. type: array minItems: 1 maxItems: 1000 items: type: string format: uuid minItems: 1 maxItems: 1 from: type: string format: date-time description: >- Start of time range that was applied when the query was run. example: '2021-10-01T00:00:00.000Z' to: type: string format: date-time description: End of time range that was applied when the query was run. example: '2021-10-02T00:00:00.000Z' '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find query run. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/queries/runs/{runId}/cancel': post: x-soph-permissions: 'xdr.query:execute' summary: Cancel query run description: Cancel a query run by ID. operationId: cancelQueryRun tags: - Runs parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: false schema: type: string format: uuid - name: runId in: path description: Query run ID. required: true schema: type: string format: uuid requestBody: required: true description: Request to cancel query run. content: application/json: schema: description: Request to cancel a query run. type: object properties: {} examples: CancelRun: value: {} responses: '200': description: Query run canceled. content: application/json: schema: type: object description: Response to cancel a query run. properties: canceled: description: Whether the query run was canceled. type: boolean '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find query run. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/queries/runs/{runId}/results': get: x-soph-permissions: 'xdr.query:read' summary: Get results description: Get the paged results for a query run. operationId: getQueryResults tags: - Runs parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: false schema: type: string format: uuid - name: runId in: path description: Query run ID. required: true schema: type: string format: uuid - in: query name: pageFromKey required: false schema: type: string description: The key of the item from where to fetch a page. - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer description: 'The page number to fetch, starting with 1.' responses: '200': description: Query run results. content: application/json: schema: description: Tabular results for a query run. type: object properties: items: description: >- Ordered list of JSON objects, one for each row in the results for the SQL query. A row JSON object has one field for each column in the SQL query. The value of the field is the value of the column. type: array items: type: object additionalProperties: true metadata: description: Metadata for tabular data in `items`. type: object properties: columns: description: List of columns. type: array items: description: Column metadata. type: object properties: name: description: Column name. type: string type: description: Column value type. type: string pages: type: object description: Page information. required: - size - maxSize properties: fromKey: type: string description: >- (Optional) The key of the first item in the returned page, returned only if the request was by key (the default if unspecified in the request). nextKey: type: string description: (Optional) The key to use when fetching the next page. size: type: integer description: The size of the page being returned. maxSize: type: integer description: The maximum page size that can be requested. current: type: integer description: >- (Optional) The 1-based page number being returned, returned only if the request was by offset. total: type: integer description: (Optional) The total number of pages that exist. items: type: integer description: (Optional) The total number of items across all pages. '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '404': description: Can't find query run. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /queries/categories: get: x-soph-permissions: 'xdr.query-catalog:read' summary: List categories description: 'Fetch all categories, built-in as well as custom.' operationId: listCategories tags: - Category parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: 'Fetch all categories, built-in as well as custom.' content: application/json: schema: type: object description: List of categories. required: - items properties: items: type: array description: List of categories. items: type: object description: Category for a query. required: - id - name - type - queryCount properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for 'canned' categories. type: string description: description: Category description. type: string icon: description: Category icon name. type: string tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. type: type: string description: Query category type. enum: - canned - custom queryCount: description: Number of queries in this category. type: integer createdAt: description: When the category was created. type: string format: datetime createdBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. updatedAt: description: When the category was last updated. type: string format: datetime updatedBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/queries/categories/{categoryId}': get: x-soph-permissions: 'xdr.query-catalog:read' summary: Get a category description: Get the details of a category. operationId: getCategory tags: - Category parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: categoryId description: Category ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Details of the requested Query. content: application/json: schema: type: object description: Category for a query. required: - id - name - type - queryCount properties: id: description: Category ID. type: string format: uuid name: description: Category name. type: string code: description: >- Identifier for category name. This is available only for 'canned' categories. type: string description: description: Category description. type: string icon: description: Category icon name. type: string tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. type: type: string description: Query category type. enum: - canned - custom queryCount: description: Number of queries in this category. type: integer createdAt: description: When the category was created. type: string format: datetime createdBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. updatedAt: description: When the category was last updated. type: string format: datetime updatedBy: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri /queries: get: x-soph-permissions: 'xdr.query-catalog:read' summary: List queries description: >- List queries by a page size related to the tenant filtered by the parameters. operationId: listQueries tags: - Query parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: query name: categoryId description: Category ID. schema: type: string format: uuid - in: query name: search description: Search for items that match the given term(s). schema: type: string - in: query name: searchFields description: Search only within the specified fields. style: form explode: false schema: type: array items: type: string - in: query name: pageSize required: false schema: type: integer default: 50 description: The size of the page requested. - in: query name: page required: false schema: type: integer default: 1 description: 'The page number to fetch, starting with 1.' - in: query name: pageTotal required: false schema: type: boolean default: false description: >- Whether the number of pages should be calculated and returned in the response. - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: List of queries. content: application/json: schema: type: object description: Page of query objects. required: - items - pages properties: items: type: array description: List of queries. items: type: object description: Saved EDR Data Lake query. required: - id - name - type - template - variables - categories properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: >- Identifier for query name. This is available only for 'canned' queries. type: string description: description: Query description. type: string template: description: >- SQL statement for a query. This can contain replacement variables wrapped in `$$` (double dollar sign) delimiters. type: string variables: description: Variables embedded in the value of `template`. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: >- Data types supported for EDR Data Lake queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: The meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url categories: description: Categories the query belongs to. type: array items: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. type: type: string description: Query type. enum: - canned - custom tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. createdAt: description: When the query was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization updatedAt: description: When the query was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization pages: type: object required: - current - size - maxSize properties: current: type: integer description: The 1-based page number being returned. size: type: integer description: The size of the page being returned. total: type: integer description: >- (Optional) The total number of pages that exist, if pageTotal=true in the request. items: type: integer description: (Optional) The total number of items across all pages. maxSize: type: integer description: The maximum page size that can be requested. '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '/queries/{queryId}': get: x-soph-permissions: 'xdr.query-catalog:read' summary: Get a query description: Get the details of a query. operationId: getQuery tags: - Query parameters: - name: X-Tenant-ID in: header description: Tenant ID. required: true schema: type: string format: uuid - in: path name: queryId description: Query ID. required: true schema: type: string format: uuid - name: fields description: The fields to return in a partial response. in: query style: form explode: false schema: type: array items: type: string responses: '200': description: Details of the requested query. content: application/json: schema: type: object description: Saved EDR Data Lake query. required: - id - name - type - template - variables - categories properties: id: description: Query ID. type: string format: uuid name: description: Query name. type: string code: description: >- Identifier for query name. This is available only for 'canned' queries. type: string description: description: Query description. type: string template: description: >- SQL statement for a query. This can contain replacement variables wrapped in `$$` (double dollar sign) delimiters. type: string variables: description: Variables embedded in the value of `template`. type: array items: type: object description: Query variable. required: - name - dataType properties: name: description: Variable name. type: string minLength: 1 maxLength: 100 dataType: type: string description: Data types supported for EDR Data Lake queries. enum: - double - integer - text - dateTime - boolean value: description: String value of the variable. type: string minLength: 1 maxLength: 5000 pivotType: type: string description: The meaning of an input parameter of a query. enum: - deviceId - deviceName - sophosPid - ipAddress - username - sha256 - filePath - registryKey - url categories: description: Categories the query belongs to. type: array items: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. type: type: string description: Query type. enum: - canned - custom tenant: type: object description: Represents a referenced object. required: - id properties: id: type: string format: uuid description: The ID of the referenced object. createdAt: description: When the query was created. type: string format: datetime createdBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization updatedAt: description: When the query was last updated. type: string format: datetime updatedBy: type: object description: Principal reference. required: - id - type properties: id: description: >- Principal ID. This is the client ID for service principals. type: string format: uuid type: description: Principal type. type: string format: enum enum: - user - service name: description: >- Principal name. This doesn't apply to service principals. type: string accountId: description: Account ID. type: string format: uuid accountType: type: string description: Account type. enum: - partner - tenant - organization '403': description: Forbidden. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri '500': description: Unexpected error. content: application/json: schema: type: object required: - error properties: error: type: string message: type: string correlationId: type: string format: uuid code: type: string createdAt: type: string format: datetime requestId: type: string format: uuid docUrl: type: string format: uri components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT