{ "openapi": "3.0.0", "x-hideTryItPanel": true, "info": { "version": "Cortex AgentiX", "title": "Cortex AgentiX APIs", "description": "Using the Cortex AgentiX APIs, you can manage authentication settings, datasets, cases, issues, and script execution. You can also run XQL queries and manage datasets, in addition to many other capabilities.\n\nThe license requirements for each API are listed individually.", "contact": { "email": "docs-cortex@paloaltonetworks.com", "name": "Cortex Documentation Team", "url": "https://cortex-docs.paloaltonetworks.com/" } }, "servers": [ { "url": "https://api-yourfqdn" } ], "paths": { "/public_api/v1/xql/start_xql_query": { "post": { "tags": [ "XQL query" ], "summary": "Start an XQL query", "description": "Execute an XQL query.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postStartXqlQuery", "parameters": [ { "name": "Authorization", "in": "header", "description": "{api_key}", "required": true, "schema": { "type": "string" } }, { "name": "x-xdr-auth-id", "in": "header", "description": "{api_key_id}", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "properties": { "query": { "type": "string", "description": "String of the XQL query." }, "tenants": { "type": "array", "description": "Note: This is only used when querying tenants managed by Managed Security Services Providers (MSSP).\n\nList of strings used for running APIs on local and Managed Security tenants. Valid values:\n- For single tenant (local tenant) query, enter a single-item list with your tenant_id. Additional valid values are, empty list ([]) or null (default).\n- For multi-tenant investigations (Managed Security parent who investigate children and/or local), enter multi-item list with the required tenant_id. List of IDs can contain the parent, children, or both parent and children.", "items": { "type": "string" } }, "timeframe": { "type": "object", "description": "Integer in timestamp epoch milliseconds.\r\nValid values include:\r\n- Absolute Unix timestamp representing a date period: {\"from\" : 1598907600000, \"to\" : 1599080399000} = date period: 31/08/20 09:00:00 PM UTC - 02/09/20 8:59:59 PM UTC\r\n- Relative Unix timestamp representing the last 24 hours: {\"relativeTime\": 86400000} = (24 * 60 * 60 * 1000 = 86400000).", "properties": { "from": { "type": "integer", "description": "Use for an absolute timeframe in Unix timestamp.", "example": 1598907600000 }, "to": { "type": "integer", "description": "Use for an absolute timeframe in Unix timestamp.", "example": 1599080399000 }, "relativeTime": { "type": "integer", "description": "Use for a relative Unix timestamp.", "example": 86400000 } } } }, "required": [ "query" ] } }, "required": [ "request_data" ], "example": { "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": [], "timeframe": { "from": 1598907600000, "to": 1599080399000 } } } }, "examples": { "default": { "$ref": "#/components/examples/default" }, "example-1": { "value": { "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": [ "431509831", "401387390" ], "timeframe": { "from": 1598907600000, "to": 1599080399000 } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "string" } }, "x-examples": { "Example 1": { "reply": "ad21c1e1492d4c_667_inv" } } }, "examples": { "Example 1": { "value": { "reply": "ad21c1e1492d4c_667_inv" } } } } } }, "400": { "description": "Bad Request. Invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API." } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/xql/get_query_results": { "post": { "tags": [ "XQL query" ], "summary": "Get XQL query results", "description": "Retrieve results of an executed XQL query API. \n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nMaximum result set size is 1000. The API does not support pagination, therefore, you can set values to determine the result size limitation and how to wait for the results. To view response with greater than 1000 results you must call [Get XQL query results Stream](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/xql-query#post-public_api-v1-xql-get_query_results_stream).\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postGetQueryResults", "parameters": [ { "name": "Authorization", "in": "header", "description": "{api_key}", "required": true, "schema": { "type": "string" } }, { "name": "x-xdr-auth-id", "in": "header", "description": "{api_key_id}", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "properties": { "query_id": { "type": "string", "description": "String representing the unique execution ID generated by the response to [Start an XQL query](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/xql-query#post-public_api-v1-xql-start_xql_query) API.\nYou can also enter the execution ID of a query generated in Cortex XDR and listed in the Query Center table." }, "pending_flag": { "type": "boolean", "description": "Boolean flag indicating whether the API call should operate in synchronous/blocking mode, or in asynchronous/non-blocking mode. Valid Values:\n- True (default): The call returns immediately with one of the following options:\n1) PENDING status indicating query hasn't yet completed or results are not yet ready to be returned. Need to execute the API call again.\n2) SUCCESS/FAIL status\n- False: The API will block until query completes and results are ready to be returned." }, "limit": { "type": "integer", "description": "Integer representing the maximum number of results to return.\nIf the 'limit' is not specified or if 'limit' is greater than 1000 and the query yields more than 1000 valid results, a `stream id` will be generated for use in the *Get XQL query results Stream** API.\nIn the context of multi-tenant investigations, when you specify the parameter value (x),\nit will return x results across all tenants combined, rather than x results for each individual tenant.\nFor example, if there are y tenants participating in the investigation, the maximum number of results returned can be x*y (up to the limit of 1,000,000)." }, "format": { "type": "string", "enum": [ "json", "csv" ], "description": "The type of response output." } }, "required": [ "query_id" ] } }, "required": [ "request_data" ], "example": { "request_data": { "query_id": "061880b4867446_4356_inv", "pending_flag": true, "limit": 100, "format": "json" } } }, "examples": { "default": { "$ref": "#/components/examples/default" }, "example-1": { "value": { "request_data": { "query_id": "061880b4867446_4356_inv", "pending_flag": true, "limit": 100, "format": "json" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "status": { "type": "string" }, "number_of_results": { "type": "integer" }, "query_cost": { "type": "object", "additionalProperties": { "type": "number" } }, "remaining_quota": { "type": "number" }, "results": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "event_id": { "type": "string" }, "agent_version": { "type": "string" }, "_product": { "type": "string" }, "_time": { "type": "integer" }, "_vendor": { "type": "string" }, "insert_timestamp": { "type": "integer" }, "agent_os_type": { "type": "string" }, "event_type": { "type": "string" }, "event_sub_type": { "type": "string" } } } } } } } } }, "x-examples": { "Example 1": { "reply": { "status": "SUCCESS", "number_of_results": 1, "query_cost": { "9995067425505": 0.01298138888888889 }, "remaining_quota": 4.969819444444444, "results": { "data": [ { "event_id": "MTQ5MDE0OTI5NjE2NDY2NTI3NA==", "agent_version": "7.7.0.60725", "_product": "Fusion", "_time": 1690877704746, "_vendor": "PANW", "insert_timestamp": 1690877878272, "agent_os_type": "AGENT_OS_WINDOWS", "event_type": "STORY", "event_sub_type": "event_sub_type_4" } ] } } } } }, "examples": { "pending_flag=true": { "value": { "reply": { "status": "PENDING" } } }, "Up to 1,000 results, JSON format, Single Tenant Investigation": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 3, "query_cost": { "tenant_id_1": 0.001596388888888889 }, "remaining_quota": 4.998403611111111, "results": { "data": [ { "event_id": "eventID1", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL" }, { "event_id": "eventID2", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL" }, { "event_id": "eventID3", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL" } ] } } } }, "Up to 1,000 results, JSON format, Multi Tenant Investigation": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 6, "query_cost": { "tenant_id_1": 0.001596388888888889, "tenant_id_2": 0.00179989 }, "remaining_quota": 4.995007332222222, "results": { "data": [ { "event_id": "eventID1", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655" }, { "event_id": "eventID2", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655" }, { "event_id": "eventID3", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1723879655" }, { "event_id": "eventID4", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706" }, { "event_id": "eventID5", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706" }, { "event_id": "eventID6", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL", "tenant": "1705396706" } ] } } } }, "More than 1,000 results": { "value": { "reply": { "status": "SUCCESS", "number_of_results": 1000000, "query_cost": { "tenant_id_1": 0.011742777777777777 }, "remaining_quota": 4.984442777777778, "results": { "stream_id": "streamID" } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/xql/get_quota": { "post": { "tags": [ "XQL query" ], "summary": "Get XQL query Quota", "description": "Retrieve the amount of query quota available and used. \n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postGetQuota", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "example": { "request_data": {} } }, "examples": { "default": { "$ref": "#/components/examples/default" } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "license_quota": { "type": "integer" }, "additional_purchased_quota": { "type": "integer" }, "used_quota": { "type": "number" }, "eval_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer", "description": "The number of daily active queries. This value is reset nightly." }, "total_daily_concurrent_rejected_queries": { "type": "integer", "description": "The number of daily queries rejected due to too many concurrent XQL queries being run through the API. This value is reset nightly." }, "current_concurrent_active_queries": { "type": "object", "description": "Currently running XQL queries with their current duration.", "additionalProperties": { "type": "string" } }, "current_concurrent_active_queries_count": { "type": "integer", "description": "The number of active queries currently running." }, "max_daily_concurrent_active_query_count": { "type": "integer", "description": "The maximum number of queries that ran concurrently today on this tenant. This value is reset nightly." } } } }, "x-examples": { "Example 1": { "reply": { "license_quota": 5, "additional_purchased_quota": 0, "used_quota": 0.07041027777777777, "eval_quota": 0 } } } }, "examples": { "example-1": { "value": { "reply": { "license_quota": 5, "additional_purchased_quota": 0, "used_quota": 0, "eval_quota": 0, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 8, "current_concurrent_active_queries": { "debee6b0c41f47_911_inv": { "xql": "config timeframe = 1mo | dataset=xdr_data | limit 1000000", "duration": 61 } }, "current_concurrent_active_queries_count": 1, "max_daily_concurrent_active_query_count": 4 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer" }, "err_msg": { "type": "string" }, "err_extra": { "type": "object", "properties": { "err_msg": { "type": "string" }, "query_cost": { "type": "integer" }, "remaining_quota": { "type": "integer" }, "total_daily_running_queries": { "type": "integer" }, "total_daily_concurrent_rejected_queries": { "type": "integer" } } } } } }, "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } }, "examples": { "Example 1": { "value": { "reply": { "err_code": 500, "err_msg": "An error occurred while processing XDR - XQL query", "err_extra": { "err_msg": "reached max allowed amount of parallel running queries. please wait for some queries to finish and submit your query again", "query_cost": 0, "remaining_quota": 5, "total_daily_running_queries": 4, "total_daily_concurrent_rejected_queries": 1 } } } } } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/xql/get_query_results_stream": { "post": { "tags": [ "XQL query" ], "summary": "Get XQL query results Stream", "description": "Retrieve XQL query results with more than 1000 results. \n\nNote: This endpoint only works on XQL queries initiated by `/public_api/v1/xql/start_xql_query/`.\n\nResponse is returned as chunked (Transfer-Encoding: chunked). To retrieve a compressed gzipped response (Content-Encoding: gzip), in your header add Accept-Encoding: gzip.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex AgentiX allows you to run up to four API queries in parallel.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postGetQueryResultsStream", "parameters": [ { "name": "Authorization", "in": "header", "description": "{api_key}", "required": true, "schema": { "type": "string" } }, { "name": "x-xdr-auth-id", "in": "header", "description": "{api_key_id}", "required": true, "schema": { "type": "string" } }, { "name": "Accept-Encoding", "in": "header", "description": "For retrieving a compressed gzipped response", "schema": { "type": "string", "default": "gzip" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "properties": { "stream_id": { "type": "string", "description": "String representing the unique ID generate by the response to [Get XQL query results](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/xql-query#post-public_api-v1-xql-get_query_results) API." }, "is_gzip_compressed": { "type": "boolean", "description": "A boolean flag." } }, "required": [ "stream_id" ] } }, "required": [ "request_data" ], "example": { "request_data": { "stream_id": "563c5e24-===-9a1f8139d3c5", "is_gzip_compressed": true } } }, "examples": { "default": { "$ref": "#/components/examples/default" } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": {} } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/scripts/run_snippet_code_script": { "post": { "tags": [ "Script execution" ], "summary": "Run Snippet Code Script", "description": "Initiate a new endpoint script execution action using provided snippet code. Cortex XDR supports sending your request in Base64.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postRunSnippetCodeScript", "parameters": [ { "name": "Authorization", "in": "header", "description": "{api_key}", "required": true, "schema": { "type": "string" } }, { "name": "x-xdr-auth-id", "in": "header", "description": "{api_key_id}", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "properties": { "filters": { "type": "array", "description": "An array of filter fields for running the script on a number of endpoints at once.", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list" ], "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs." }, "operator": { "type": "string", "enum": [ "in" ], "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings" }, "value": { "type": "array", "description": "Value that this filter must match.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "timeout": { "type": "integer", "description": "The timeout in seconds for this execution. Default value is 600.", "default": 600 }, "snippet_code": { "type": "string", "description": "Section of a script you want to initiate on an endpoint." }, "incident_id": { "type": "string", "description": "Case ID.\nWhen included in the request, the **Run Snippet Code Script** action will appear in the **Cortex AgentiX Case View Timeline** tab." } }, "required": [ "filters", "snippet_code" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "snippet_code": "print (\"7\")" } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "snippet_code": "print (\"7\")" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "string", "description": " ID of the action initiated. ID will be used as a reference to track in the action center." }, "endpoints_count": { "type": "integer", "description": "Number of endpoints the action was initiated on." } } } }, "x-examples": { "example-1": { "reply": { "action_id": "", "endpoints_count": 21 } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "", "endpoints_count": 21 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/scripts/run_script": { "post": { "tags": [ "Script execution" ], "summary": "Run Script", "description": "Initiate a new endpoint script execution action using a script from the script library. The script can be run on up to 1000 endpoints.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postRunScript", "parameters": [ { "name": "Authorization", "in": "header", "description": "{api_key}", "required": true, "schema": { "type": "string" } }, { "name": "x-xdr-auth-id", "in": "header", "description": "{api_key_id}", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "properties": { "filters": { "type": "array", "description": "Array of filter fields for running the script on a number of endpoints at once.", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list" ], "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs." }, "operator": { "type": "string", "enum": [ "in" ], "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords and values are:\n`in`\n- `endpoint_id_list`: List of strings", "default": "in" }, "value": { "type": "array", "description": "Value that this filter must match.", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "script_uid": { "type": "string", "description": "GUID, unique identifier of the script, returned by the [Get Scripts](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/script-execution#post-public_api-v1-scripts-get_scripts) API per script." }, "parameters_values": { "type": "object", "description": "Dictionary containing the parameter name, `key`, and its value for this execution, `value`.\n\nYou can obtain these values by running [Get Script Metadata](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/script-execution#post-public_api-v1-scripts-get_script_metadata) API.", "properties": { "x": { "type": "string" }, "y": { "type": "integer" } }, "required": [ "x", "y" ] }, "timeout": { "type": "integer", "description": "Timeout in seconds for this execution. Default value is 600.", "default": 600 }, "incident_id": { "type": "string", "description": "Case ID.\nWhen included in the request, the **Run Script** action will appear in the **Cortex AgentiX Case View Timeline** tab." } }, "required": [ "filters", "script_uid" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "script_uid": "", "parameters_values": { "x": "param input as returned in Get Script Metadata", "y": 4 } } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "script_uid": "", "parameters_values": { "x": "param input as returned in Get Script Metadata", "y": 4 } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "action_id": { "type": "integer", "description": "ID of the action initiated. ID will be used as a reference to track in the action center." }, "endpoints_count": { "type": "integer", "description": "Number of endpoints the action was initiated on." }, "status": { "type": "integer", "description": "Integer representing whether the action:\n- 1: succeeded\n- 0: failed" } } } }, "x-examples": { "example-1": { "reply": { "action_id": 22519813685366, "status": 1, "endpoints_count": 1 } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": 22519813685366, "status": 1, "endpoints_count": 1 } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "401": { "description": "Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "402": { "description": "Unauthorized access. User does not have the required license type to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } }, "500": { "description": "Internal server error. A unified status for API communication type errors.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/scripts/get_script_metadata": { "post": { "tags": [ "Script execution" ], "summary": "Get Script Metadata", "description": "Get the full definitions of a specific script in the scripts library.\n\nRequired license: **Cortex AgentiX Enterprise** or **Cortex AgentiX Base**", "operationId": "postGetScriptMetadata", "parameters": [ { "name": "Authorization", "in": "header", "description": "{api_key}", "required": true, "schema": { "type": "string" } }, { "name": "x-xdr-auth-id", "in": "header", "description": "{api_key_id}", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "properties": { "script_uid": { "type": "string", "description": "Unique identifier of the script, returned by the [Get Scripts](https://app.gitbook.com/s/jP7n9HvCP3W3VmkFvzE2/cortex-agentix/script-execution#post-public_api-v1-scripts-get_scripts) API per script." } }, "required": [ "script_uid" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "script_uid": "" } } } }, "examples": { "example-1": { "value": { "request_data": { "script_uid": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "script_id": { "type": "string", "description": "Script ID." }, "name": { "type": "string", "description": "Name of script." }, "description": { "type": "string", "description": "Description of script." }, "modification_date": { "type": "integer", "description": "Timestamp of when the script was last modified." }, "created_by": { "type": "string", "description": "Name of the user who created the script." }, "is_high_risk": { "type": "boolean", "description": "Whether the script has a high-risk outcome." }, "windows_supported": { "type": "boolean", "description": "Whether the script can be executed on Windows OS." }, "linux_supported": { "type": "boolean", "description": "Whether the script can be executed on Linux OS." }, "macos_supported": { "type": "boolean", "description": "Whether the script can be executed on macOS." }, "script_uid": { "type": "string", "description": "GUID, global ID of the script, used toidentify the script when executing." }, "entry_point": { "type": "string", "description": "name of the entry point selected for the script defined as `run`." }, "script_input": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "friendly_name": { "type": "string" } } } }, "script_output_type": { "type": "string", "enum": [ "auto_detect", "dictionary", "number_list", "number", "string", "string_list", "boolean_list", "ip", "ip_list", "boolean" ], "description": "Type of output." }, "script_output_dictionary_definitions": { "type": "array", "description": "When the `script_output_type` is a dictionary an array with `friendly_name`, `name`, and `type` for each output is returned.\nThe field is empty in all other cases.", "items": { "type": "object", "properties": { "friendly_name": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } } } } } }, "x-examples": { "example-1": { "reply": { "script_id": "