Get a list of agent configurations
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31. Default value is2023-10-31.
GET
/api/apm/settings/agent-configuration
curl \
--request GET 'https://localhost:5601/api/apm/settings/agent-configuration' \
--header "Authorization: $API_KEY" \
--header "elastic-api-version: 2023-10-31"
Response examples (200)
An example of a successful response from `GET /api/apm/settings/agent-configuration`.
[
{
"agent_name": "go",
"service": {
"name": "opbeans-go",
"environment": "production"
},
"settings": {
"transaction_sample_rate": "1",
"capture_body": "off",
"transaction_max_spans": "200"
},
"@timestamp": 1581934104843,
"applied_by_agent": false,
"etag": "1e58c178efeebae15c25c539da740d21dee422fc"
},
{
"agent_name": "go",
"service": {
"name": "opbeans-go"
},
"settings": {
"transaction_sample_rate": "1",
"capture_body": "off",
"transaction_max_spans": "300"
},
"@timestamp": 1581934111727,
"applied_by_agent": false,
"etag": "3eed916d3db434d9fb7f039daa681c7a04539a64"
},
{
"agent_name": "nodejs",
"service": {
"name": "frontend"
},
"settings": {
"transaction_sample_rate": "1",
},
"@timestamp": 1582031336265,
"applied_by_agent": false,
"etag": "5080ed25785b7b19f32713681e79f46996801a5b"
}
]
Get connector types
You do not need any Kibana feature privileges to run this API.
Query parameters
-
feature_id
string A filter to limit the retrieved connector types to those that support a specific feature (such as alerting or cases).
GET
/api/actions/connector_types
curl \
--request GET 'https://localhost:5601/api/actions/connector_types' \
--header "Authorization: $API_KEY"
Response examples (200)
[
{
"id": ".gen-ai",
"name": "OpenAI",
"enabled": true,
"enabled_in_config": true,
"enabled_in_license": true,
"is_system_action_type": false,
"supported_feature_ids": [
"generativeAIForSecurity",
"generativeAIForObservability",
"generativeAIForSearchPlayground"
],
"minimum_license_required": "enterprise"
},
{
"id": ".bedrock",
"name": "AWS Bedrock",
"enabled": true,
"enabled_in_config": true,
"enabled_in_license": true,
"is_system_action_type": false,
"supported_feature_ids": [
"generativeAIForSecurity",
"generativeAIForObservability",
"generativeAIForSearchPlayground"
],
"minimum_license_required": "enterprise"
},
{
"id": ".gemini",
"name": "Google Gemini",
"enabled": true,
"enabled_in_config": true,
"enabled_in_license": true,
"is_system_action_type": false,
"supported_feature_ids": [
"generativeAIForSecurity"
],
"minimum_license_required": "enterprise"
}
]Path parameters
-
id
string Required An identifier for the connector.
Body
-
name
string Required The display name for the connector.
config
object The connector configuration details.
One of: bedrock_configobject crowdstrike_configobject d3security_configobject email_configobject gemini_configobject resilient_configobject index_configobject jira_configobject defender_configobject genai_azure_configobject genai_openai_configobject opsgenie_configobject pagerduty_configobject sentinelone_configobject servicenow_configobject servicenow_itom_configobject slack_api_configobject swimlane_configobject thehive_configobject tines_configobject torq_configobject webhook_configobject cases_webhook_configobject xmatters_configobject Defines properties for connectors when type is
.bedrock.secrets
object One of: bedrock_secretsobject crowdstrike_secretsobject d3security_secretsobject email_secretsobject gemini_secretsobject resilient_secretsobject jira_secretsobject teams_secretsobject genai_secretsobject opsgenie_secretsobject pagerduty_secretsobject sentinelone_secretsobject servicenow_secretsobject slack_api_secretsobject swimlane_secretsobject thehive_secretsobject tines_secretsobject torq_secretsobject webhook_secretsobject cases_webhook_secretsobject xmatters_secretsobject Defines secrets for connectors when type is
.bedrock.
PUT
/api/actions/connector/{id}
curl \
--request PUT 'https://localhost:5601/api/actions/connector/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"name":"updated-connector","config":{"index":"updated-index"}}'
Request example
{
"name": "updated-connector",
"config": {
"index": "updated-index"
}
}Update a runtime field
Body
Required
-
runtimeField
object Required The runtime field definition object.
You can update following fields:
typescript
POST
/api/data_views/data_view/{viewId}/runtime_field/{fieldName}
curl \
--request POST 'https://localhost:5601/api/data_views/data_view/ff959d40-b880-11e8-a6d9-e546fe2bba5f/runtime_field/hour_of_day' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"runtimeField":{"script":{"source":"emit(doc[\"bar\"].value)"}}}'
Request example
{
"runtimeField": {
"script": {
"source": "emit(doc[\"bar\"].value)"
}
}
}Get a full agent policy
Get a full agent policy by ID.
[Required authorization] Route required privileges: fleet-agent-policies-read.
Path parameters
-
agentPolicyId
string Required
Query parameters
-
download
boolean -
standalone
boolean -
kubernetes
boolean
GET
/api/fleet/agent_policies/{agentPolicyId}/full
curl \
--request GET 'https://localhost:5601/api/fleet/agent_policies/{agentPolicyId}/full' \
--header "Authorization: $API_KEY"Get agents
[Required authorization] Route required privileges: fleet-agents-read.
Query parameters
-
page
number -
perPage
number Default value is
20. -
kuery
string -
showAgentless
boolean Default value is
true. -
showInactive
boolean Default value is
false. -
withMetrics
boolean Default value is
false. -
showUpgradeable
boolean Default value is
false. -
getStatusSummary
boolean Default value is
false. -
sortField
string -
sortOrder
string Values are
ascordesc. -
searchAfter
string -
openPit
boolean -
pitId
string -
pitKeepAlive
string
GET
/api/fleet/agents
curl \
--request GET 'https://localhost:5601/api/fleet/agents' \
--header "Authorization: $API_KEY"Delete an uploaded file
Delete a file uploaded by an agent.
[Required authorization] Route required privileges: fleet-agents-all.
Path parameters
-
fileId
string Required
DELETE
/api/fleet/agents/files/{fileId}
curl \
--request DELETE 'https://localhost:5601/api/fleet/agents/files/{fileId}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"Delete assets for an input package
[Required authorization] Route required privileges: integrations-all AND fleet-agent-policies-all.
Path parameters
-
pkgName
string Required -
pkgVersion
string Required
Query parameters
-
packagePolicyId
string Required
DELETE
/api/fleet/epm/packages/{pkgName}/{pkgVersion}/datastream_assets
curl \
--request DELETE 'https://localhost:5601/api/fleet/epm/packages/{pkgName}/{pkgVersion}/datastream_assets?packagePolicyId=string' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"Get settings
[Required authorization] Route required privileges: fleet-settings-read.
GET
/api/fleet/settings
curl \
--request GET 'https://localhost:5601/api/fleet/settings' \
--header "Authorization: $API_KEY"Delete a package policy
Delete a package policy by ID.
[Required authorization] Route required privileges: fleet-agent-policies-all AND integrations-all.
Path parameters
-
packagePolicyId
string Required
Query parameters
-
force
boolean
DELETE
/api/fleet/package_policies/{packagePolicyId}
curl \
--request DELETE 'https://localhost:5601/api/fleet/package_policies/{packagePolicyId}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"Update a Fleet Server host
Update a Fleet Server host by ID.
[Required authorization] Route required privileges: fleet-settings-all.
Path parameters
-
itemId
string Required
Body
-
host_urls
array[string] At least
1element. -
is_default
boolean -
is_internal
boolean -
name
string -
proxy_id
string | null Required -
secrets
object Additional properties are NOT allowed.
-
ssl
object | null Additional properties are NOT allowed.
PUT
/api/fleet/fleet_server_hosts/{itemId}
curl \
--request PUT 'https://localhost:5601/api/fleet/fleet_server_hosts/{itemId}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"host_urls":["string"],"is_default":true,"is_internal":true,"name":"string","proxy_id":"string","secrets":{"ssl":{"es_key":{"id":"string"},"key":{"id":"string"}}},"ssl":{"certificate":"string","certificate_authorities":["string"],"client_auth":"optional","es_certificate":"string","es_certificate_authorities":["string"],"es_key":"string","key":"string"}}'
Update a maintenance window.
Generally available; added in 9.1.0
[Required authorization] Route required privileges: write-maintenance-window.
Path parameters
-
id
string Required
Body
-
enabled
boolean Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
-
schedule
object Additional properties are NOT allowed.
-
scope
object Additional properties are NOT allowed.
-
title
string The name of the maintenance window. While this name does not have to be unique, a distinctive name can help you identify a specific maintenance window.
PATCH
/api/maintenance_window/{id}
curl \
--request PATCH 'https://localhost:5601/api/maintenance_window/{id}' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: true" \
--data '{"enabled":true,"schedule":{"custom":{"duration":"string","recurring":{"end":"string","every":"string","occurrences":42.0,"onMonth":[42.0],"onMonthDay":[42.0],"onWeekDay":["string"]},"start":"string","timezone":"string"}},"scope":{"alerting":{"query":{"kql":"string"}}},"title":"string"}'
GET
/api/detection_engine/index
curl \
--request GET 'https://localhost:5601/api/detection_engine/index' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"name": ".alerts-security.alerts-default",
"index_mapping_outdated": false
}
POST
/api/detection_engine/index
curl \
--request POST 'https://localhost:5601/api/detection_engine/index' \
--header "Authorization: $API_KEY"Retrieve the status of prebuilt detection rules and Timelines
Retrieve the status of all Elastic prebuilt detection rules and Timelines.
This endpoint provides detailed information about the number of custom rules, installed prebuilt rules, available prebuilt rules that are not installed, outdated prebuilt rules, installed prebuilt timelines, available prebuilt timelines that are not installed, and outdated prebuilt timelines.
GET
/api/detection_engine/rules/prepackaged/_status
curl \
--request GET 'https://localhost:5601/api/detection_engine/rules/prepackaged/_status' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"rules_installed": 0,
"rules_not_updated": 0,
"rules_not_installed": 112,
"timelines_installed": 0,
"timelines_not_updated": 0,
"rules_custom_installed": 0,
"timelines_not_installed": 0
}Get endpoint exception list items
Get a list of all endpoint exception list items.
Query parameters
-
filter
string(nonempty) Filters the returned results according to the value of the specified field, using the
<field name>:<field value>syntax.Minimum length is
1. -
page
integer The page number to return
Minimum value is
0. -
per_page
integer The number of exception list items to return per page
Minimum value is
0. -
sort_field
string(nonempty) Determines which field is used to sort the results
Minimum length is
1. -
sort_order
string Determines the sort order, which can be
descorascValues are
descorasc.
GET
/api/endpoint_list/items/_find
curl \
--request GET 'https://localhost:5601/api/endpoint_list/items/_find' \
--header "Authorization: $API_KEY"List asset criticality records
List asset criticality records, paging, sorting and filtering as needed.
Query parameters
-
sort_field
string The field to sort by.
Values are
id_value,id_field,criticality_level, or\@timestamp. -
sort_direction
string The order to sort by.
Values are
ascordesc. -
page
integer The page number to return.
Minimum value is
1. -
per_page
integer The number of records to return per page.
Minimum value is
1, maximum value is1000. -
kuery
string The kuery to filter by.
GET
/api/asset_criticality/list
curl \
--request GET 'https://localhost:5601/api/asset_criticality/list' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"page": 1,
"total": 2,
"records": [
{
"host": {
"name": "my_other_host",
"asset": {
"criticality": "medium_impact"
}
},
"asset": {
"criticality": "medium_impact"
},
"id_field": "host.name",
"id_value": "my_other_host",
"@timestamp": "2024-08-02T14:40:35.705Z",
"criticality_level": "medium_impact"
},
{
"host": {
"name": "my_host",
"asset": {
"criticality": "high_impact"
}
},
"asset": {
"criticality": "high_impact"
},
"id_field": "host.name",
"id_value": "my_host",
"@timestamp": "2024-08-02T11:15:34.290Z",
"criticality_level": "high_impact"
}
],
"per_page": 10
}Create rule exception items
Create exception items that apply to a single detection rule.
Path parameters
-
id
string(uuid) Required Detection rule's identifier
POST
/api/detection_engine/rules/{id}/exceptions
curl \
--request POST 'https://localhost:5601/api/detection_engine/rules/330bdd28-eedf-40e1-bed0-f10176c7f9e0/exceptions' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"items":[{"name":"Sample Exception List Item","tags":["malware"],"type":"simple","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["saturn","jupiter"],"operator":"included"}],"item_id":"simple_list_item","list_id":"simple_list","os_types":["linux"],"description":"This is a sample detection type exception item.","namespace_type":"single"}]}'
Request example
{
"items": [
{
"name": "Sample Exception List Item",
"tags": [
"malware"
],
"type": "simple",
"entries": [
{
"type": "exists",
"field": "actingProcess.file.signer",
"operator": "excluded"
},
{
"type": "match_any",
"field": "host.name",
"value": [
"saturn",
"jupiter"
],
"operator": "included"
}
],
"item_id": "simple_list_item",
"list_id": "simple_list",
"os_types": [
"linux"
],
"description": "This is a sample detection type exception item.",
"namespace_type": "single"
}
]
}
Response examples (200)
[
{
"id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
"name": "Sample Exception List Item",
"tags": [
"malware"
],
"type": "simple",
"entries": [
{
"type": "exists",
"field": "actingProcess.file.signer",
"operator": "excluded"
},
{
"type": "match_any",
"field": "host.name",
"value": [
"saturn",
"jupiter"
],
"operator": "included"
}
],
"item_id": "simple_list_item",
"list_id": "simple_list",
"_version": "WzQsMV0=",
"comments": [],
"os_types": [
"linux"
],
"created_at": "2025-01-07T20:07:33.119Z",
"created_by": "elastic",
"updated_at": "2025-01-07T20:07:33.119Z",
"updated_by": "elastic",
"description": "This is a sample detection type exception item.",
"namespace_type": "single",
"tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c"
}
]
Response examples (400)
Bad payload
{
"error": "Bad Request",
"message": "Invalid request payload JSON format",
"statusCode": 400
}{
"error": "Bad Request",
"message": "[request params]: id: Invalid uuid",
"statusCode": 400
}
Response examples (401)
{
"error": "Unauthorized",
"message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
"statusCode": 401
}
Response examples (403)
{
"message": "Unable to create exception-list",
"status_code": 403
}
Response examples (500)
{
"message": "Internal Server Error",
"status_code": 500
}Upgrade assistant
The assistant helps you prepare for the next major version of Elasticsearch.