{ "openapi": "3.0.0", "x-hideTryItPanel": true, "info": { "version": "Cortex Cloud 2.2", "title": "Cortex Cloud Platform APIs", "description": " Using the Cortex Platform APIs, you can configure and manage authentication settings, datasets, cases, issues, and script executions. Additionally, the APIs allow you to run XQL queries and perform various other operations across the platform.\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/cli/releases/version": { "get": { "operationId": "GetPublicCLIVersion", "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" } } ], "tags": [ "Cortex CLI" ], "x-go-middlewares": [ "CustomLogging" ], "x-public": true, "summary": "Get the latest version of the Cortex CLI.", "description": "Get the latest version of Cortex CLI.\n\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionObj" } } } }, "400": { "description": "Bad Request. Invalid Input." }, "401": { "description": "Unauthorized access. User does not have the required license type to run this API." }, "403": { "description": "Forbidden access. The provided API Key does not have the required RBAC permissions to run this API." }, "500": { "description": "Service had unexpected internal error" } } } }, "/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/ZuJbX2x7VQJhNovscCwE/cortex-platform/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex allows you to run up to four API queries in parallel.\n\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "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": { "value": { "request_data": { "query": "dataset=xdr_data | fields event_id, event_type, event_sub_type | limit 3", "tenants": [], "timeframe": { "from": 1598907600000, "to": 1599080399000 } } } }, "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**.\n\nFor more information on how to run XQL queries, see [Run XQL Query APIs](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex allows you to run up to four API queries in parallel.\n\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "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/ZuJbX2x7VQJhNovscCwE/cortex-platform/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": { "value": { "request_data": { "query_id": "061880b4867446_4356_inv", "pending_flag": true, "limit": 100, "format": "json" } } }, "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" }, { "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" }, { "event_id": "eventID4", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825324, "_time": 1621541523000, "event_type": "STORY", "event_sub_type": "NULL" }, { "event_id": "eventID5", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825326, "_time": 1621541528000, "event_type": "STORY", "event_sub_type": "NULL" }, { "event_id": "eventID6", "_vendor": "PANW", "_product": "Fusion", "insert_timestamp": 1621541825325, "_time": 1621541517000, "event_type": "STORY", "event_sub_type": "NULL" } ] } } } }, "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/ZuJbX2x7VQJhNovscCwE/cortex-platform/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex allows you to run up to four API queries in parallel.\n\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "operationId": "postGetQuota", "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", "example": { "request_data": {} } }, "examples": { "default": { "value": { "request_data": {} } } } } } }, "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/ZuJbX2x7VQJhNovscCwE/cortex-platform/run-xql-query-apis).\n\n\n\n> #### Note\n>\n> To ensure you don't surpass your quota, Cortex allows you to run up to four API queries in parallel.\n\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "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/ZuJbX2x7VQJhNovscCwE/cortex-platform/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": { "value": { "request_data": { "stream_id": "563c5e24-===-9a1f8139d3c5", "is_gzip_compressed": true } } } } } } }, "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/distributions/get_versions": { "post": { "tags": [ "Endpoint Management" ], "summary": "Get Distribution version", "description": "Get a list of all the agent versions to use for creating a distribution list.\n\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "operationId": "postGetVersions", "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" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "windows": { "type": "array", "description": "List of Windows agent versions.", "items": { "type": "string" } }, "linux": { "type": "array", "description": "List of Linux agent versions.", "items": { "type": "string" } }, "macos": { "type": "array", "description": "List of Mac agent versions.", "items": { "type": "string" } } } } }, "x-examples": { "example-1": { "reply": { "windows": [ "", "", "", "" ], "linux": [ "", "", "", "" ], "macos": [ "", "", "" ] } } } } } } }, "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/endpoints/get_endpoints": { "post": { "tags": [ "Endpoint Management" ], "summary": "Get all Endpoints", "description": "Gets a list of all of your endpoints. The response is concatenated using AND condition (OR is not supported).\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postGetEndpoints", "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" } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "array", "items": { "type": "object", "properties": { "agent_id": { "type": "string" }, "agent_status": { "type": "string" }, "operational_status": { "type": "string" }, "host_name": { "type": "string" }, "agent_type": { "type": "string" }, "ip": { "type": "array", "items": { "type": "string" } }, "last_seen": { "type": "integer" }, "tags": { "type": "object", "properties": { "server_tags": { "type": "array", "items": { "type": "object" } }, "endpoint_tags": { "type": "array", "items": { "type": "object" } } } }, "users": { "type": "array", "items": { "type": "string" } } } } } }, "x-examples": { "Example 1": { "reply": [ { "agent_id": "", "agent_status": "DISCONNECTED", "operational_status": "PROTECTED", "host_name": "", "agent_type": "Workstation", "ip": [ "" ], "last_seen": 1678012587521, "tags": { "server_tags": [], "endpoint_tags": [] }, "users": [ "user" ] } ] } } }, "examples": { "example-1": { "value": { "reply": [ { "agent_id": "", "agent_status": "DISCONNECTED", "operational_status": "PROTECTED", "host_name": "", "agent_type": "Workstation", "ip": [ "" ], "last_seen": 1678012587521, "tags": { "server_tags": [], "endpoint_tags": [] }, "users": [ "user" ] } ] } } } } } }, "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/endpoints/get_policy": { "post": { "tags": [ "Endpoint Management" ], "summary": "Get Policy", "description": "Get the policy name for a specific endpoint.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postGetPolicy", "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", "properties": { "endpoint_id": { "type": "string", "description": "Endpoint ID." } }, "required": [ "endpoint_id" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "endpoint_id": "" } } } }, "examples": { "example-1": { "value": { "request_data": { "endpoint_id": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "policy_name": { "type": "string", "description": "Name of the policy allocated with the endpoint." } } } }, "x-examples": { "example-1": { "reply": { "policy_name": "Windows Default" } } } }, "examples": { "example-1": { "value": { "reply": { "policy_name": "Windows Default" } } } } } } }, "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/endpoints/delete": { "post": { "tags": [ "Endpoint Management" ], "summary": "Delete Endpoints", "description": "Delete the selected endpoints. You can delete up to 1000 endpoints.\n\nNote: Endpoints are deleted from Cortex UI, however they still exist in the database.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 1000.\n- Offset is the zero-based number of cases from the start of the result set.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postDelete", "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", "properties": { "filters": { "type": "array", "description": "Array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "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. Valid keywords:\n- `endpoint_id_list`: List of strings", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } } } } }, "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ] } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ] } } } } } } }, "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/distributions/create": { "post": { "operationId": "postCreate", "summary": "Create distributions", "description": "Create an installation package. This is an async call that returns the distribution ID; it does not mean that the creation succeeded. To confirm the package has been created, check the status of the distribution by running the **Get Distribution Status** API.\r\n\r\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "Authorization", "description": "{api_key}", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-xdr-auth-id", "description": "{api_key_id}", "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "request_data": { "name": "", "platform": "windows", "package_type": "standalone", "agent_version": "" } } }, "required": [ "request_data" ], "properties": { "request_data": { "type": "object", "required": [ "name", "package_type", "agent_version", "deployment_platform", "default_namespace", "run_on_master_node", "run_on_all_nodes" ], "properties": { "name": { "type": "string", "description": "The name of the installation package." }, "platform": { "type": "string", "description": "The installation platform.", "enum": [ "windows", "linux", "macos", "android", "serverless" ] }, "package_type": { "type": "string", "description": "A string representing the type of package to create. Each JSON object must contain *one* of the following keywords:\n- `standalone`: Installation for a new agent. When using this, you must include the `platform` field with one of the following values: `windows`, `linux`, `macos`, `android`, `kubernetes`, `helm`.\n- `upgrade`: Upgrade of an agent from ESM. When using this, you must include the `agent_version` field with one of the following values: `windows_version`, `linux_version`, or `macos_version`.\n- `serverless`: Create a serverless distribution. When using this, you must include the `yaml_preferences` field with the following properties: `runtime` (Node.js or python), `deployment_type` (embedded or layers), `cloud_provider` (aws), and `restrictions_profile` (Serverless restrictions profile ID).\n- `caas_embedded`: Container-embedded XDR agent installation using the CaaS Generic Installer (Linux dockerfile-based deployment)." }, "agent_version": { "type": "string", "description": "Use `agent_version` when creating a standalone installer. The value should be the agent version number.\n" }, "windows_version": { "type": "string", "description": "Use `windows_version` when creating an upgrade package. The value is the relevant version number." }, "linux_version": { "type": "string", "description": "Use `linux_version` when creating an upgrade package. The value is the relevant version number." }, "macos_version": { "type": "string", "description": "Use `macos_version` when creating an upgrade package. The value is the relevant version number." }, "deployment_platform": { "type": "string", "description": "When the `package_type` is `kubernetes` or `helm`, use the `deployment_platform` to indicate the type of platform. Valid values include:\n- `standard`\n- `openshift`\n- `gcos`\n- `bottlerocket`\n- `gke_autopilot`" }, "default_namespace": { "type": "string", "description": "The default namespace" }, "node_selector": { "type": "object", "description": "The node selector in the following format:\n`\"node_selector\": {\"key\": \"val\"}'", "additionalProperties": {} }, "proxy": { "type": "array", "items": { "type": "string" } }, "cluster_name": { "type": "string", "description": "Cluster name" }, "run_on_master_node": { "type": "boolean", "description": "Whether or not to run on the master node." }, "run_on_all_nodes": { "type": "boolean", "description": "Whether or not to run on all nodes." }, "description": { "type": "string", "description": "A description for the distribution package." }, "endpoint_tags": { "type": "array", "description": "List of endpoint tags to associate with the distribution package. Tags must already exist in the system.", "items": { "type": "string" } }, "yaml_preferences": { "type": "object", "description": "Configuration for serverless distributions.", "properties": { "runtime": { "type": "string", "enum": [ "Node.js", "python" ], "description": "The runtime environment for the serverless function." }, "deployment_type": { "type": "string", "enum": [ "embedded", "layers" ], "description": "The deploy method used for the serverless agent." }, "cloud_provider": { "type": "string", "enum": [ "aws" ], "description": "The cloud service provider hosting the serverless function. Currently only AWS is supported." }, "restrictions_profile": { "type": "string", "description": "The serverless restrictions profile ID." } } } } } } }, "examples": { "New Installation example": { "value": { "request_data": { "name": "", "package_type": "upgrade", "agent_version": "windows_version", "deployment_platform": "standard", "default_namespace": "cortex-xdr", "run_on_master_node": true, "run_on_all_nodes": false, "endpoint_tags": [ "Administrator", "DevTeam" ], "description": "Created using Public APIs" } } }, "Upgrade example": { "value": { "request_data": { "name": "Upgrade package", "package_type": "upgrade", "agent_version": "windows_version", "deployment_platform": "standard", "default_namespace": "cortex-xdr", "run_on_master_node": true, "run_on_all_nodes": false, "endpoint_tags": [ "Administrator", "DevTeam" ], "description": "Created using Public APIs" } } }, "Kubernetes distribution": { "value": { "request_data": { "name": "PAPI Dist K8s", "description": "Created using PAPI", "endpoint_tags": [ "new-tag" ], "package_type": "kubernetes", "platform": "linux", "agent_version": "8.8.0.10594", "deployment_platform": "standard", "default_namespace": "cortex-xdr", "node_selector": { "key": "val" }, "proxy": [ "10.10.10.1:8080" ], "cluster_name": "some_name", "run_on_master_node": true, "run_on_all_nodes": false } } }, "Serverless distribution": { "value": { "request_data": { "name": "Serverless distribution", "package_type": "serverless", "description": "Description", "agent_version": "{version}", "platform": "serverless", "deployment_platform": "standard", "default_namespace": "cortex-xdr", "run_on_master_node": false, "run_on_all_nodes": false, "yaml_preferences": { "runtime": "Node.js", "deployment_type": "embedded", "cloud_provider": "aws", "restrictions_profile": "28" } } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "reply": { "distribution_id": "" } } }, "properties": { "reply": { "type": "object", "properties": { "distribution_id": { "type": "string", "description": "Installation package ID." } } } } } } } }, "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" } } } } }, "tags": [ "Endpoint Management" ] } }, "/public_api/v1/distributions/get_distributions": { "post": { "summary": "Get Distributions", "description": "Retrieves a paginated list of existing agent installations and metadata based on optional filters and sorting criteria.\n\nThis endpoint allows you to:\n\n- Retrieve existing agent installations or filter by specific criteria\n- Paginate through large result sets\n- Sort results by any field in ascending or descending order\n- Get total count and filtered count of agent installations\n", "operationId": "get_distributions", "tags": [ "Endpoint Management" ], "requestBody": { "required": true, "description": "Request body containing pagination, sorting, and filtering criteria for agent distributions", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "request_data": { "search_from": 0, "search_to": 5, "sort": { "field": "distribution_id", "keyword": "asc" }, "filters": [ { "field": "distribution_id", "operator": "eq", "value": "068bcaad02974ac5b223bfa786e7573c" }, { "field": "name", "operator": "contains", "value": "macos-369121" }, { "field": "description", "operator": "contains", "value": "macos-369121" }, { "field": "package_type", "operator": "eq", "value": "standalone" }, { "field": "package_type", "operator": "eq", "value": "standalone" }, { "field": "platform", "operator": "eq", "value": "macos" }, { "field": "agent_version", "operator": "contains", "value": "9.1." }, { "field": "status", "operator": "eq", "value": "completed" } ] } } }, "properties": { "request_data": { "$ref": "#/components/schemas/GetDataRequest" } } }, "examples": { "Sorting and all filter options": { "value": { "request_data": { "search_from": 0, "search_to": 5, "sort": { "field": "distribution_id", "keyword": "asc" }, "filters": [ { "field": "distribution_id", "operator": "eq", "value": "068bcaad02974ac5b223bfa786e7573c" }, { "field": "name", "operator": "contains", "value": "macos-369121" }, { "field": "description", "operator": "contains", "value": "Production-ready macos agent installer with enhanced monitoring capabilities" }, { "field": "package_type", "operator": "eq", "value": "standalone" }, { "field": "platform", "operator": "eq", "value": "macos" }, { "field": "agent_version", "operator": "contains", "value": "9.1." }, { "field": "status", "operator": "eq", "value": "completed" } ] } } } } } } }, "responses": { "200": { "description": "Successful response containing the list of distributions matching the criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicGetDataResponse" }, "examples": { "Example 1": { "value": { "reply": { "data": [ { "distribution_id": "068bcaad02974ac5b223bfa786e7573c", "name": "macos-369121", "description": "Production-ready macos agent installer with enhanced monitoring capabilities", "package_type": "standalone", "platform": "macos", "agent_version": "9.1.0.9877", "status": "completed", "tags": [ "production", "stable" ], "eol_time": 1735689600, "created_by": "John Doe", "creation_time": 1704067200, "modification_time": 1704153600, "supported_packages": [ "pkg" ] } ], "filter_count": 1, "total_count": 10 } } } } } } }, "400": { "description": "Bad Request - Invalid request parameters or malformed JSON", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "search_from: Input should be greater than or equal to 0" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "summary": "Invalid pagination parameters", "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Unsupported operator 'contains' for field platform" } } }, "Example 2": { "value": { "reply": { "err_code": 400, "err_msg": "Got an invalid input while processing XDR public API.", "err_extra": "Search size must fulfill the requirement: 0 < search_size <= 100" } } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred on the server", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "reply": { "err_code": 500, "err_msg": "An unexpected error occurred by XDR public API", "err_extra": "Invalid value 'serverless_functions' for field platform" } } }, "properties": { "reply": { "type": "object", "properties": { "err_code": { "type": "integer", "description": "Numeric error code returned by the API." }, "err_msg": { "type": "string", "description": "Human-readable summary of the error." }, "err_extra": { "type": "string", "description": "Detailed description of the error, including the cause and how to resolve it when applicable." } } } } }, "examples": { "Example 1": { "summary": "Internal server error", "value": { "reply": { "err_code": 500, "err_msg": "An unexpected error occurred by XDR public API", "err_extra": "Invalid value 'serverless_functions' for field platform" } } }, "Example 2": { "value": { "reply": { "err_code": 500, "err_msg": "Got an invalid input while processing XDR public API", "err_extra": "Invalid parameter names: creation_time" } } } } } } } }, "parameters": [ { "schema": { "type": "string", "example": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP" }, "in": "header", "required": true, "name": "Authorization", "description": "{api_key}" }, { "schema": { "type": "string", "example": "241" }, "in": "header", "required": true, "name": "x-xdr-auth-id", "description": "{api_key_id}" } ] } }, "/public_api/v1/device_control/get_violations": { "post": { "tags": [ "Endpoint Management" ], "summary": "Get Violations", "description": "Gets a list of device control violations filtered by selected fields. You can retrieve up to 100 violations.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 100.\n- Offset is the zero-based number of cases from the start of the result set.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postGetViolations", "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": "You can send a request to retrieve either *all* or *filtered* results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "description": "An empty object returns all results.", "properties": { "filters": { "type": "array", "description": "Provides an array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list", "type", "timestamp", "ip_list", "vendor", "vendor_id", "product", "product_id", "serial", "hostname", "violation_id_list", "username" ], "description": "String that identifies the violation field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `type`: Type of violation.\n- `timestamp`: Timestamp of the violation.\n- `ip_list`: List of IP addresses.\n- `vendor`: Name of vendor.\n- `vendor_id`: Vendor ID.\n- `product`: Name of product.\n- `product_id`: Product ID.\n- `serial`: Serial number.\n- `hostname`: Hostname.\n- `violation_id_list`: List of violation IDs.\n- `username`: Username." }, "operator": { "type": "string", "enum": [ "in", "gte", "lte" ], "description": "String that identifies the comparison operator you want to use for this filter. Valid keywords are:\n`in`\n— Permitted for all fields except `timestamp`.\n`gte` / `lte`\n— Permitted only for `timestamp`." }, "value": { "description": "Value that this filter must match. The contents of this field will differ depending on the violation field that you specified for this filter:\n- `timestamp`: Integer, in UTC timezone epoch milliseconds\n- `violation_id_list`: List of integers\n- `ip_list`: Must contain an IP string\n- `type`: Must be either `cd-rom`, `disk drive`, `floppy disk`, `portable device`\n- All other fields need to be list of strings.", "oneOf": [ { "type": "array", "items": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] } }, { "type": "integer" }, { "type": "string" } ] } }, "required": [ "field", "operator", "value" ] } }, "search_from": { "type": "integer", "description": "Integer representing the starting offset within the query result set from which you want violations returned.\nViolations are returned as a zero-based list. Any violation indexed less than this value is not returned in the final result set and defaults to zero." }, "search_to": { "type": "integer", "description": "An integer representing the end of offset within the result set after which you do not want violations returned.\nViolations in the violation list that are indexed higher than this value are not returned in the final results set. Defaults to zero, which returns all alerts to the end of the list." }, "sort": { "type": "object", "description": "Identifies the sort order for the result set.", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list", "type", "timestamp", "ip_list", "vendor", "vendor_id", "product", "product_id", "serial", "hostname", "violation_id_list", "username" ], "description": "The field you want to sort by." }, "value": { "type": "string", "enum": [ "asc", "desc" ], "description": "Can be either `asc` (ascending) or `desc` (descending).", "default": "desc" } }, "required": [ "field", "value" ] } } } }, "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "type", "operator": "in", "value": [ "disk drivE" ] } ], "search_to": 1 } } } }, "examples": { "Request all results": { "value": { "request_data": {} } }, "Request filtered results": { "value": { "request_data": { "filters": [ { "field": "type", "operator": "in", "value": [ "disk drive" ] } ], "search_to": 1 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "total_count": { "type": "integer", "description": "Number of total results of this filter without paging." }, "result_count": { "type": "integer", "description": "Number of alerts actually returned as a result." }, "violations": { "type": "array", "items": { "$ref": "#/components/schemas/violation" } } } } }, "x-examples": { "example-1": { "reply": { "total_count": 10, "result_count": 1, "violations": [ { "hostname": "", "username": "test", "ip": "", "timestamp": 1576260019000, "violation_id": 11, "type": "Disk Drive", "vendor_id": "", "vendor": "", "product_id": "", "product": "", "serial": "", "endpoint_id": "" } ] } } } } } } }, "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/distributions/get_status": { "post": { "tags": [ "Endpoint Management" ], "summary": "Get Distribution status", "description": "Check the status of the installation package.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postGetStatus", "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", "properties": { "distribution_id": { "type": "string", "description": "The installation package ID." } }, "required": [ "distribution_id" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "distribution_id": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the installation package." } } } }, "x-examples": { "example-1": { "reply": { "status": "Completed" } } } } } } }, "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/distributions/get_dist_url": { "post": { "tags": [ "Endpoint Management" ], "summary": "Get Distribution URL", "description": "Get the distribution URL for downloading the installation package.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postGetDistUrl", "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", "properties": { "distribution_id": { "type": "string", "description": "Installation package ID." }, "package_type": { "type": "string", "description": "A string representing the type of installation package. Select *one* of the following valid keywords and values:\n- `upgrade`\nPackage type should match the distribution type or platform:\n- `sh`: x86_64 Linux SH installer\n- `rpm`: x86_64 Linux RPM installer\n- `deb`: x86_64 Linux DEB installer\n- `aarch64_sh`: aarch64 Linux SH installer\n- `aarch64_rpm`: aarch64 Linux RPM installer\n- `aarch64_deb`: aarch64 Linux DEB installer\n- `pkg`: Mac\n- `x86`: Windows\n- `x64`: Windows\n- `arm`: Windows ARM64" } }, "required": [ "distribution_id", "package_type" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "distribution_id": "", "package_type": "x86" } } } }, "examples": { "example-1": { "value": { "request_data": { "distribution_id": "", "package_type": "x86" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "distribution_url": { "type": "string", "description": "URL for downloading the installation package." } } } }, "x-examples": { "example-1": { "reply": { "distribution_url": "" } } } }, "examples": { "example-1": { "value": { "reply": { "distribution_url": "" } } } } } } }, "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/endpoints/update_agent_name": { "post": { "tags": [ "Endpoint Management" ], "summary": "Set an Endpoint Alias", "description": "Set or modify an Alias field for your endpoints.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postUpdateAgentName", "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", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list", "endpoint_status", "dist_name", "ip_list", "group_name", "platform", "alias", "isolate", "hostname", "cloud_provider", "cloud_region", "cloud_provider_account_id", "cloud_instance_id", "cloud_id" ], "description": "String that identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `endpoint_status`: Status of the endpoint ID.\n- `dist_name`: Distribution / Installation Package name.\n- `ip_list`: List of IP addresses.\n- `group_name`: Group name the agent belongs to.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `isolate`: If the endpoint was isolated.\n- `hostname`: Hostname.\n- `cloud_provider`: Cloud provider (for example, AWS, GCP, Azure).\n- `cloud_region`: Cloud region where the endpoint is deployed.\n- `cloud_provider_account_id`: Cloud provider account ID.\n- `cloud_instance_id`: Cloud instance ID of the endpoint.\n- `cloud_id`: Cloud ID of the endpoint." }, "operator": { "type": "string", "enum": [ "in", "gte", "lte" ], "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`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings.\n- `endpoint_status`: Permitted values are `connected` or `disconnected`\n- `ip_list`: List of strings, for example 192.168.5.12.\n- `platform`: Permitted values are `windows`, `linux`, `macos`, or `android`\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.\n- `cloud_provider`, `cloud_region`, `cloud_provider_account_id`, `cloud_instance_id`, `cloud_id`: List of strings." }, "value": { "description": "Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:\n- `endpoint_id_list`, `dist_name`, `hostname`, `alias`, `group_name`: List of strings.\n- `endpoint_status`: Must contain only the following valid values: `connected` or `disconnected`\n- `ip_list`: String list of IP addresses.\n- `platform`: Must contain only the following valid values: `windows`, `linux`, `macos`, or `android`.\n- `isolate`: Must contain only the following valid values: `isolated` or `unisolated`.\n- `cloud_provider`, `cloud_region`, `cloud_provider_account_id`, `cloud_instance_id`, `cloud_id`: List of strings.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] } }, "required": [ "field", "operator", "value" ] } }, "alias": { "type": "string", "description": "The alias name you want to set or modify.\n\nNote: If you send an empty field, the current alias name is deleted." } } } }, "x-examples": { "example-1": { "context": { "lcaas_id": "" }, "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "alias": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=The alias name was set or modified successfully." } } } }, "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/tags/agents/create": { "post": { "tags": [ "Endpoint Management" ], "summary": "Create Tag", "description": "Create a new agent tag in the `endpoint_tags` family.\n\nThe tag name must be a string of no more than 64 characters and must not contain wildcard characters (for example, `*`). If a tag with the same name already exists, the request fails with a 409 error.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postCreateTag", "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", "properties": { "tag": { "type": "string", "maxLength": 64, "description": "The name of the tag to create. Maximum 64 characters. Wildcard characters (for example, `*`) are not allowed." } }, "required": [ "tag" ] } }, "required": [ "request_data" ] }, "examples": { "example-1": { "value": { "request_data": { "tag": "my-tag" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "string", "description": "Confirmation message, for example: \"Successfully created a new tag - my-tag\"." } } } }, "400": { "description": "Bad Request. The tag is missing, not a string, exceeds 64 characters, or contains invalid characters.", "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" } } } }, "409": { "description": "Conflict. A tag with the same name already exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reply" } } } } }, "servers": [ { "url": "https://api-yourfqdn" } ] } }, "/public_api/v1/tags/agents/assign": { "post": { "tags": [ "Endpoint Management" ], "summary": "Assign Tags", "description": "Assign one or more tags to one or more endpoints.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postAssign", "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", "properties": { "filters": { "type": "array", "description": "An array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id", "endpoint_id_list", "last_seen", "first_seen", "dist_name", "ip_list", "platform", "alias", "hostname", "isolate", "username", "scan_status", "group_name", "endpoint_status", "operational_status", "public_ip_list", "cloud_provider", "cloud_region", "cloud_provider_account_id", "cloud_instance_id", "cloud_id" ], "description": "String that identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `last_seen`: When an endpoint was last seen.\n- `first_seen`: When an endpoint was first seen.\n- `dist_name`: Distribution / Installation Package name.\n- `ip_list`: List of IP addresses.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `hostname`: Hostname.\n- `isolate`: If the endpoint was isolated.\n- `username`: Name of user.\n- `scan_status`: Status of the scan.\n- `group_name`: Group name the agent belongs to.\n- `endpoint_status`: Status of the endpoint ID.\n- `operational_status`: Operational status.\n- `public_ip_list`: List of public IP addresses.\n- `cloud_provider`: Cloud provider (for example, AWS, GCP, Azure).\n- `cloud_region`: Cloud region where the endpoint is deployed.\n- `cloud_provider_account_id`: Cloud provider account ID.\n- `cloud_instance_id`: Cloud instance ID of the endpoint.\n- `cloud_id`: Cloud ID of the endpoint." }, "operator": { "type": "string", "enum": [ "in", "gte", "lte" ], "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`, `dist_name`, `group_name`, `alias`, `hostname`, `username`, `operational_status`: List of strings.\n- `endpoint_status`: Permitted values are `connected`, `lost`, `disconnected`, `uninstalled`.\n- `ip_list`, `public_ip_list`: List of strings, for example \"192.168.5.12\".\n- `platform`: Permitted values are `windows`, `linux`, `macos`, `android`, `ios`.\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n- `operational_status`: Permitted values are `protected`, `partially_protected`, `unprotected`.\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.\n- `cloud_provider`, `cloud_region`, `cloud_provider_account_id`, `cloud_instance_id`, `cloud_id`: List of strings." }, "value": { "description": "Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:\n- `endpoint_id_list`, `dist_name`, `group_name`, `alias`, `hostname`, `username`, `operational_status`: List of strings.\n- `endpoint_status`: Must contain only the following valid values: `connected`, `disconnected`, `lost`, or `uninstalled`.\n- `operational_status`: Must contain only the following valid values: `protected`, `partially_protected`, `unprotected`.\n- `ip_list`, `public_ip_list`: String list of IP addresses.\n- `platform`: Must contain only the following valid values: `windows`, `linux`, `macos`, `android`, or `ios`.\n- `isolate`: Must contain only the following valid values: `isolated` or `unisolated`.\n- `scan_status`: Must contain only the following valid values: `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.\n- `cloud_provider`, `cloud_region`, `cloud_provider_account_id`, `cloud_instance_id`, `cloud_id`: List of strings.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" }, { "type": "integer" } ] } }, "required": [ "field", "operator", "value" ] } }, "tag": { "type": "string", "description": "The tag you want to assign." } } } }, "x-examples": { "example-1": { "context": { "lcaas_id": "" }, "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "tag": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=The tag name was assigned successfully." } } } }, "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": "x 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/tags/agents/remove": { "post": { "tags": [ "Endpoint Management" ], "summary": "Remove Tags", "description": "Remove one or more tags from one or more endpoints.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postRemove", "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 following API request fields.", "properties": { "filters": { "type": "array", "description": "Array of filter fields.", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list", "endpoint_status", "dist_name", "ip_list", "group_name", "platform", "alias", "isolate", "hostname", "cloud_provider", "cloud_region", "cloud_provider_account_id", "cloud_instance_id", "cloud_id" ], "description": "String that identifies the field the filter is matching. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `endpoint_status`: Status of the endpoint ID.\n- `dist_name`: Distribution / Installation Package name.\n- `ip_list`: List of IP addresses.\n- `group_name`: Group name the agent belongs to.\n- `platform`: Platform name.\n- `alias`: Alias name.\n- `isolate`: If the endpoint was isolated.\n- `hostname`: Hostname.\n- `cloud_provider`: Cloud provider (for example, AWS, GCP, Azure).\n- `cloud_region`: Cloud region where the endpoint is deployed.\n- `cloud_provider_account_id`: Cloud provider account ID.\n- `cloud_instance_id`: Cloud instance ID of the endpoint.\n- `cloud_id`: Cloud ID of the endpoint." }, "operator": { "type": "string", "enum": [ "in", "gte", "lte" ], "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`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings.\n- `endpoint_status`: Permitted values are `connected` or `disconnected`.\n- `ip_list`: List of strings, for example 192.168.5.12.\n- `platform`: Permitted values are `windows`, `linux`, `macos`, or `android`.\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`.\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds.\n- `cloud_provider`, `cloud_region`, `cloud_provider_account_id`, `cloud_instance_id`, `cloud_id`: List of strings." }, "value": { "description": "Value that this filter must match. The contents of this field will differ depending on the endpoint field that you specified for this filter:\n- `endpoint_id_list`, `distribution_name`, `hostname`, `alias`, `group_name`: List of strings.\n- `endpoint_status`: Must contain only the following valid values: `connected` or `disconnected`\n- `ip_list`: String list of IP addresses.\n- `platform`: Must contain only the following valid values: `windows`, `linux`, `macos`, or `android`.\n- `isolate`: Must contain only the following valid values: `isolated` or `unisolated`.\n- `cloud_provider`, `cloud_region`, `cloud_provider_account_id`, `cloud_instance_id`, `cloud_id`: List of strings.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" }, { "type": "integer" } ] } }, "required": [ "field", "operator", "value" ] } }, "tag": { "type": "string", "description": "The tag you want to remove." } } } }, "x-examples": { "example-1": { "context": { "lcaas_id": "" }, "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "tag": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=tag name removed successfully." } } } }, "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": "Unauthorized access. User does not have the required license type 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/endpoints/restore": { "post": { "tags": [ "Response Action" ], "summary": "Restore File", "description": "Restore a quarantined file on a requested endpoints.\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 100.\n- Offset is the zero-based number of cases from the start of the result set.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postRestore", "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": { "file_hash": { "type": "string", "description": "String that represents the file in hash. Hash must be a valid SHA256." }, "endpoint_id": { "type": "string", "description": "String that represents the endpoint ID.\nNote: if it is not specified, the request will run restore on all endpoints which relate to the quarantined file you defined." }, "incident_id": { "type": "integer", "description": "String representing the case ID.\nWhen included in the request, the Restore File action will appear in the Cortex Case View Timeline tab." } }, "required": [ "file_hash" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "file_hash": "", "incident_id": 302 } } } }, "examples": { "example-1": { "value": { "request_data": { "file_hash": "", "incident_id": 302 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "action_id": { "type": "string" }, "endpoints_count": { "type": "string" } } } }, "x-examples": { "example-1": { "reply": { "action_id": "", "endpoints_count": "673" } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "", "status": 1, "endpoints_count": "673" } } } } } } }, "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/actions/file_retrieval_details": { "post": { "tags": [ "Response Action" ], "summary": "File Retrieval Details", "description": "View the API required to call in order to download the file retrieved by the [Retrieve File](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/response-action#post-public_api-v1-endpoints-file_retrieval) API request according to the action ID.\n\nThe response contains a file hash you need to download and then unzip to view:\n1. Download the file.\n\n\n``` curl\ncurl -XPOST \"https://api-{fqdn}/public_api/v1/download/\" \n-H \"x-xdr-auth-id:{API_KEY_ID}\" \n-H \"Authorization:{API_KEY}\" \n-H 'Content-Type:application/json' \n--output /tmp/file.zip\n```\n2. Unzip the file: `unzip /tmp/file.zip`\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postFileRetrievalDetails", "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": { "group_action_id": { "type": "string", "description": "The action ID of the [Retrieve File](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/response-action#post-public_api-v1-endpoints-file_retrieval) API response." } }, "required": [ "group_action_id" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "group_action_id": "" } } } }, "examples": { "example-1": { "value": { "request_data": { "group_action_id": "" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "data": { "type": "object", "properties": { "endpoint_ID": { "type": "string", "description": "API required to call in order to download the retrieved result." } } } } } }, "x-examples": { "example-1": { "reply": { "data": { "": "https://api-{fqdn}/public_api/v1/download/" } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "": "https://api-{fqdn}/public_api/v1/download/" } } } } } } } }, "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/hash_exceptions/allowlist": { "post": { "tags": [ "Response Action" ], "summary": "Allow List Files", "description": "Add files which do not exist in the allow or block lists to an allow list.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postAllowlist", "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": { "hash_list": { "type": "array", "description": "A list of hashed files you want to add to the allow list. Hash must be a valid SH256.", "items": { "type": "string" } }, "comment": { "type": "string", "description": "Additional information regarding the action." }, "incident_id": { "type": "integer", "description": "The case ID related to the hash.\nWhen included in the request, the **Allow List** action will appear in the **Cortex Case View Timeline** tab." } }, "required": [ "hash_list" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF29E5D553E4", "365296EB1B---FCF69E3D553E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF79E5D553D4" ], "comment": "test", "incident_id": 5 } } } }, "examples": { "example-1": { "value": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF29E5D553E4", "365296EB1B---FCF69E3D553E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF79E5D553D4" ], "comment": "test", "incident_id": 5 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=File successfully added to the allow list." } } } }, "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/quarantine/status": { "post": { "tags": [ "Response Action" ], "summary": "Get Quarantine Status", "description": "Retrieve the quarantine status for specified files.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postStatus", "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", "properties": { "files": { "type": "array", "description": "Array of endpoint IDs, filepaths, and file hash.", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string", "description": "Endpoint ID" }, "file_path": { "type": "string", "description": "File hash. Must be a valid SHA256." }, "file_hash": { "type": "string", "description": "File path." } } } } }, "required": [ "files" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "files": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "" } ] } } } }, "examples": { "example-1": { "value": { "request_data": { "files": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "" } ] } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "array", "items": { "type": "object", "properties": { "endpoint_id": { "type": "string", "description": "Endpoint ID." }, "file_path": { "type": "string", "description": "File path." }, "file_hash": { "type": "string", "description": "File hash." }, "status": { "type": "boolean", "description": "The file's status.\nTrue: The file is quarantined.\nFalse: The file is not quarantined." } } } } }, "x-examples": { "example-1": { "reply": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "", "status": false } ] } } }, "examples": { "example-1": { "value": { "reply": [ { "endpoint_id": "", "file_path": "C:\\\\test_x64.msi", "file_hash": "", "status": false } ] } } } } } }, "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/endpoints/quarantine": { "post": { "tags": [ "Response Action" ], "summary": "Quarantine Files", "description": "Quarantine file on selected endpoints. You can select up to 1000 endpoints.\n\nNote: A success response means that the request reached the defined endpoints, however if the file was not found there, no quarantine action will take place. To ensure if the file has been quarantined, check the Cortex XDR Action Center.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Maximum result set size is 1000.\n- Offset is the zero-based number of cases from the start of the result set.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postQuarantine", "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.", "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. Valid keywords:\n- `endpoint_id_list`: Array of strings", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "file_path": { "type": "string", "description": "The path of the file you want to quarantine. You must enter a proper path and not symbolic links." }, "file_hash": { "type": "string", "description": "Case ID.\nWhen included in the request, the **Quarantine File** action will appear in the **Cortex Case View Timeline** tab." } }, "required": [ "filters", "file_path", "file_hash" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "file_path": "C:\\\\test_x64.msi", "file_hash": "" } } } }, "examples": { "example-1": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] } ], "file_path": "C:\\\\test_x64.msi", "file_hash": "" } } } } } } }, "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": "Action ID of action to quarantine selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the file quarantine succeeded either:\n- In the Cortex console, navigate to **Response** > **Action Center** and search for the action ID. Make sure the **Action ID** field is selected in the table **Layout** settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/response-action#post-public_api-v1-actions-get_action_status) API request." }, "status": { "type": "string", "description": "Integer representing whether the action:\n- 1: succeeded\n- 0: failed" }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } }, "x-examples": { "example-1": { "reply": { "action_id": "[ID value]", "status": "1", "endpoints_count": "673" } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "[ID value]", "status": "1", "endpoints_count": "673" } } } } } } }, "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/hash_exceptions/blocklist": { "post": { "tags": [ "Response Action" ], "summary": "Block List Files", "description": "Add files which do not exist in the allow or block lists to a block list. You can view the block list in the UI at **Investigation & Response** > Response > **Action Center** > **Block List**.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postBlocklist", "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": { "hash_list": { "type": "array", "description": "A list of hashed files you want add to a block list. Hash must be a valid SH256.", "items": { "type": "string" } }, "comment": { "type": "string", "description": "Additional information regarding the action." }, "incident_id": { "type": "integer", "description": "The case ID related to the hash.\nWhen included in the request, the **Block List** action appears in the **Cortex Case View Timeline** tab." } }, "required": [ "hash_list" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF69E7D553E4", "365296EB1B---FCF69E5D523E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF63E5D553D4" ], "comment": "test", "incident_id": 5 } } } }, "examples": { "example-1": { "value": { "request_data": { "hash_list": [ "032196FB1A---DFCF69E5D553F0", "365296EB1B---FCF69E7D553E4", "365296EB1B---FCF69E5D523E4", "365296EB1B---FCF69E5D553D4", "365296EB1B---FCF63E5D553D4" ], "comment": "test", "incident_id": 5 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "boolean", "description": "true=File successfully added to block list." } } } }, "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/endpoints/unisolate": { "post": { "tags": [ "Response Action" ], "summary": "Unisolate Endpoints", "description": "Reverse the isolation of one or more endpoints in single request.\n\nNote: You can only send a request with either `endpoint_id` to unisolate one endpoint or with filters to unisolate more than one endpoint. An error is raised if you try to use both `endpoint_id` and the filters.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postUnisolate", "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": "One of `endpoint_id` of `filters` is required, but not both.", "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 unisolating a number of endpoints at once.\nNote: This field is only required if unisolating more than one endpoint.", "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. Valid keywords:\n- `endpoint_id_list`: List of strings", "items": { "type": "string" } } }, "required": [ "field", "operator", "value" ] } }, "endpoint_id": { "type": "string", "description": "The ID of the endpoint to unisolate.\n\nNote: this field is only required if unisolating one endpoint." }, "incident_id": { "type": "string", "description": "Case ID.\nWhen included in the request, the **Unisolate Endpoints** action will appear in the **Cortex Case View Timeline** tab." } }, "required": [ "endpoint_id" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "dist_name", "operator": "IN", "value": [ "MG" ] } ] } } } }, "examples": { "Unisolate one endpoint": { "value": { "request_data": { "endpoint_id": "" } } }, "Unisolate more than one endpoint": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "IN", "value": [ "", "", "" ] } ] } } } } } } }, "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 to unisolate selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the endpoint was restored either:\n- In the Cortex XDR console, navigate to **Response** > **Action Center** > **Isolation** and search for the action ID. Make sure the **Action ID** field is selected in the table **Layout** settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/response-action#post-public_api-v1-actions-get_action_status) API request." }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } }, "x-examples": { "example-1": { "reply": { "action_id": "", "status": "1", "endpoints_count": "673" } } } }, "examples": { "example-1": { "value": { "reply": { "action_id": "", "status": "1", "endpoints_count": "673" } } } } } } }, "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/endpoints/abort_scan": { "post": { "tags": [ "Response Action" ], "summary": "Cancel Scan Endpoints", "description": "Cancel the scan of selected endpoints. A scan can only be aborted if the selected endpoints are in **Pending** or in **Progress** status.\n\nWhen filtering by multiple fields:\n- Response is concatenated using AND condition (OR is not supported).\n- Offset is the zero-based number of endpoints from the start of the result set.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postAbortScan", "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": { "description": "An array of filter fields to filter which endpoints to cancel scanning.\nTo cancel scan of all endpoints, use the value \"all\".", "oneOf": [ { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "endpoint_id_list", "dist_name", "first_seen", "last_seen", "ip_list", "group_name", "platform", "alias", "isolate", "hostname", "username" ], "description": "String that identifies a list the filters match. Filters are based on the following keywords:\n- `endpoint_id_list`: List of endpoint IDs.\n- `dist_name`: Name of the distribution list.\n- `first_seen`: When an endpoint was first seen.\n- `last_seen`: When an endpoint was last seen.\n- `ip_list`: List of IP addresses.\n- `group_name`: Name of endpoint group.\n- `platform`: Type of operating system.\n- `alias`: Endpoint alias name.\n- `isolate`: If an endpoint has been isolated.\n- `hostname`: Name of host.\n- `username`: Name of user." }, "operator": { "type": "string", "enum": [ "in", "gte", "lte" ], "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`, `dist_name`, `group_name`, `alias`, `hostname`, `username`: List of strings\n- `ip_list`: List of strings, for example 192.168.5.12\n- `platform`: Permitted values are `windows`, `linux`, `macos`, `android`\n- `isolate`: Permitted values are `isolated` or `unisolated`\n- `scan_status`: Permitted values are `none`, `pending`, `in_progress`, `canceled`, `aborted`, `pending_cancellation`, `success`, or `error`\n`gte` / `lte`\n- `first_seen` and `last_seen`: Integer in timestamp epoch milliseconds." }, "value": { "description": "Value that this filter must match. Valid keywords:\n- `first_seen`, `last_seen`: Integer in timestamp epoch milliseconds, UTC timezone\n- `endpoint_id_list`, `dist_name`, `hostname`, `alias`, `group_name`: List of strings\n- `ip_list`: List of strings, for example 192.168.5.12\n- `isolate`: Permitted values are `isolated` or `unisolated`.\n- `platform`: Permitted values are `windows`, `linux`, `macos`, or `android`.", "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "integer" }, { "type": "string" } ] } }, "required": [ "field", "operator", "value" ] } }, { "type": "string" } ] }, "incident_id": { "type": "string", "description": "Case ID.\nWhen included in the request, the **Cancel Scan Endpoints** action will appear in the **Cortex Case View Timeline** tab." } }, "required": [ "filters" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } } }, "examples": { "To cancel scan of all endpoints": { "value": { "request_data": { "filters": "all" } } }, "To cancel scan of filtered endpoints": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } } } } } }, "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 action to cancel scan selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the scan succeeded either:\n- In Cortex XDR console, navigate to **Response** > **Action Center** and search for the action ID. Make sure the **Action ID** field is selected in the table Layout settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/response-action#post-public_api-v1-actions-get_action_status) API request." }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } }, "x-examples": { "example-1": { "reply": { "action_id": "", "status": "1", "endpoints_count": "673" } } } } } } }, "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/endpoints/scan": { "post": { "tags": [ "Response Action" ], "summary": "Scan Endpoints", "description": "Run a scan on selected endpoints.\n- Response is concatenated using AND condition (OR is not supported).\n- Offset is the zero-based number of cases from the start of the result set.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postScan", "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": "Note: You can send a request to retrieve either **all** or **filtered** results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_data": { "type": "object", "description": "A dictionary containing the API request fields.", "properties": { "filters": { "type": "string", "enum": [ "all" ], "description": "An array of filter fields. To scan all endpoints, use the value `all`." }, "incident_id": { "type": "string", "description": "Case ID.\nWhen included in the request, the **Scan Endpoints** action will appear in the **Cortex Case View Timeline** tab." } }, "required": [ "filters" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } } }, "examples": { "Scan all endpoints": { "value": { "request_data": { "filters": "all" } } }, "Scan filtered endpoints": { "value": { "request_data": { "filters": [ { "field": "endpoint_id_list", "operator": "in", "value": [ "" ] }, { "field": "dist_name", "operator": "in", "value": [ "WinInstaller" ] }, { "field": "group_name", "operator": "in", "value": [ "test\"" ] }, { "field": "scan_status", "operator": "in", "value": [ "none", "pending", "in_progress", "pending_cancellation", "aborted", "success" ] }, { "field": "group_name", "operator": "in", "value": [ "test" ] } ] } } } } } } }, "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 action to scan selected endpoints.\nResponse only indicates the request was successfully sent to the endpoint. To track if the scan was successful either:\n- In Cortex XDR console, navigate to **Response** > **Action Center** > **All Actions** and search for the action ID. Make sure the **Action ID** field is selected in the table **Layout** settings.\n- Send a [Get Action Status](https://app.gitbook.com/s/ZuJbX2x7VQJhNovscCwE/cortex-platform/response-action#post-public_api-v1-actions-get_action_status) API request." }, "endpoints_count": { "type": "string", "description": "Number of endpoints included in the request." } } } }, "x-examples": { "example-1": { "reply": { "action_id": "", "endpoints_count": "673" } } } } } } }, "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/actions/get_action_status": { "post": { "tags": [ "Response Action" ], "summary": "Get Action Status", "description": "Retrieve the status of the requested actions according to the action ID.\n\n**Required license:** Cortex Cloud Runtime Security. In Cortex Cloud Posture Security, you need the Cortex Cloud Runtime Security add-on.", "operationId": "postGetActionStatus", "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": { "group_action_id": { "type": "integer", "description": "Action ID of the selected request." } }, "required": [ "group_action_id" ] } }, "required": [ "request_data" ], "x-examples": { "example-1": { "request_data": { "group_action_id": "" } } } }, "examples": { "example-1": { "value": { "request_data": { "group_action_id": 123456789 } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "description": "JSON object containing the query result.", "properties": { "data": { "type": "object", "properties": { "agent_id": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "CANCELLED", "PENDING_ABORT", "ABORTED", "EXPIRED", "COMPLETED_PARTIAL", "COMPLETED_SUCCESSFULLY", "FAILED", "TIMEOUT" ] } } } } } }, "x-examples": { "example-1": { "reply": { "data": { "": "COMPLETED_SUCCESSFULLY" } } } } }, "examples": { "example-1": { "value": { "reply": { "data": { "": "COMPLETED_SUCCESSFULLY" } } } } } } } }, "400": { "description": "Bad Request. Got an invalid JSON.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reply": { "type": "object", "properties": { "data": { "type": "object", "description": "JSON object containing the query result.", "additionalProperties": {} }, "errorReasons": { "type": "object", "description": "Returns all error messages the agent returns to allow for easier analysis." } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "5a763600a3e44928a94ba84b6088380f": "FAILED" }, "errorReasons": { "5a763600a3e44928a94ba84b6088380f": { "errorData": "{\"reportIds\":[\"0ca3c1ace7694fcd8b44b735e5ba6c04\"],\"errorText\":\"\"}", "terminated_by": "instance_id", "errorDescription": "Element not found.\r\n", "terminate_result": [ { "path": null, "status": 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": { "data": { "type": "object", "description": "JSON object containing the query result.", "additionalProperties": {} }, "errorReasons": { "type": "object", "description": "Returns all error messages the agent returns to allow for easier analysis." } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "5a763600a3e44928a94ba84b6088380f": "FAILED" }, "errorReasons": { "5a763600a3e44928a94ba84b6088380f": { "errorData": "{\"reportIds\":[\"0ca3c1ace7694fcd8b44b735e5ba6c04\"],\"errorText\":\"\"}", "terminated_by": "instance_id", "errorDescription": "Element not found.\r\n", "terminate_result": [ { "path": null, "status": 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": { "data": { "type": "object", "description": "JSON object containing the query result.", "additionalProperties": {} }, "errorReasons": { "type": "object", "description": "Returns all error messages the agent returns to allow for easier analysis." } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "5a763600a3e44928a94ba84b6088380f": "FAILED" }, "errorReasons": { "5a763600a3e44928a94ba84b6088380f": { "errorData": "{\"reportIds\":[\"0ca3c1ace7694fcd8b44b735e5ba6c04\"],\"errorText\":\"\"}", "terminated_by": "instance_id", "errorDescription": "Element not found.\r\n", "terminate_result": [ { "path": null, "status": 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": { "data": { "type": "object", "description": "JSON object containing the query result.", "additionalProperties": {} }, "errorReasons": { "type": "object", "description": "Returns all error messages the agent returns to allow for easier analysis." } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "5a763600a3e44928a94ba84b6088380f": "FAILED" }, "errorReasons": { "5a763600a3e44928a94ba84b6088380f": { "errorData": "{\"reportIds\":[\"0ca3c1ace7694fcd8b44b735e5ba6c04\"],\"errorText\":\"\"}", "terminated_by": "instance_id", "errorDescription": "Element not found.\r\n", "terminate_result": [ { "path": null, "status": 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": { "data": { "type": "object", "description": "JSON object containing the query result.", "additionalProperties": {} }, "errorReasons": { "type": "object", "description": "Returns all error messages the agent returns to allow for easier analysis." } } } } }, "examples": { "Example 1": { "value": { "reply": { "data": { "5a763600a3e44928a94ba84b6088380f": "FAILED" }, "errorReasons": { "5a763600a3e44928a94ba84b6088380f": { "errorData": "{\"reportIds\":[\"0ca3c1ace7694fcd8b44b735e5ba6c04\"],\"errorText\":\"\"}", "terminated_by": "instance_id", "errorDescription": "Element not found.\r\n", "terminate_result": [ { "path": null, "status": 1 } ] } } } } } } } } } }, "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\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "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 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\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "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/ZuJbX2x7VQJhNovscCwE/cortex-platform/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/ZuJbX2x7VQJhNovscCwE/cortex-platform/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 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\n**Required license:** Cortex Cloud Runtime Security or Cortex Cloud Posture Management.", "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/ZuJbX2x7VQJhNovscCwE/cortex-platform/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": "