Kibana Security Entity Analytics API API
Use the Security entity analytics APIs to manage entity analytics and risk scoring, including asset criticality, privileged user monitoring, and entity engines.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions Security Entity Analytics API API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- description: 'Use the Security entity analytics APIs to manage entity analytics and risk scoring, including asset criticality, privileged user monitoring, and entity engines.
'
name: Security Entity Analytics API
x-displayName: Security entity analytics
paths:
/api/asset_criticality:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/asset_criticality</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Delete the asset criticality record for a specific entity.'
operationId: DeleteAssetCriticalityRecord
parameters:
- description: The ID value of the asset.
example: my_host
in: query
name: id_value
required: true
schema:
type: string
- description: The field representing the ID.
example: host.name
in: query
name: id_field
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IdField'
- description: If 'wait_for' the request will wait for the index refresh.
in: query
name: refresh
required: false
schema:
enum:
- wait_for
type: string
responses:
'200':
content:
application/json:
schema:
type: object
properties:
deleted:
description: True if the record was deleted or false if the record did not exist.
type: boolean
record:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecord'
description: The deleted record if it existed.
required:
- deleted
description: Successful response
'400':
description: Invalid request
summary: Delete an asset criticality record
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/asset_criticality</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the asset criticality record for a specific entity.'
operationId: GetAssetCriticalityRecord
parameters:
- description: The ID value of the asset.
example: my_host
in: query
name: id_value
required: true
schema:
type: string
- description: The field representing the ID.
example: host.name
in: query
name: id_field
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IdField'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecord'
description: Successful response
'400':
description: Invalid request
'404':
description: Criticality record not found
summary: Get an asset criticality record
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/asset_criticality</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Create or update an asset criticality record for a specific entity.
If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn''t exist for the specified entity, a new record is created.
'
operationId: CreateAssetCriticalityRecord
requestBody:
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_CreateAssetCriticalityRecord'
- type: object
properties:
refresh:
description: If 'wait_for' the request will wait for the index refresh.
enum:
- wait_for
type: string
example:
criticality_level: high_impact
id_field: host.name
id_value: my_host
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecord'
description: Successful response
'400':
description: Invalid request
summary: Upsert an asset criticality record
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/asset_criticality/bulk:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/asset_criticality/bulk</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Bulk upsert up to 1000 asset criticality records.
If asset criticality records already exist for the specified entities, those records are overwritten with the specified values. If asset criticality records don''t exist for the specified entities, new records are created.
'
operationId: BulkUpsertAssetCriticalityRecords
requestBody:
content:
application/json:
schema:
example:
records:
- criticality_level: low_impact
id_field: host.name
id_value: host-1
- criticality_level: medium_impact
id_field: host.name
id_value: host-2
type: object
properties:
records:
items:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecordIdParts'
- type: object
properties:
criticality_level:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevelsForBulkUpload'
required:
- criticality_level
maxItems: 1000
minItems: 1
type: array
required:
- records
responses:
'200':
content:
application/json:
schema:
example:
errors:
- index: 0
message: Invalid ID field
stats:
failed: 1
successful: 1
total: 2
type: object
properties:
errors:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityBulkUploadErrorItem'
type: array
stats:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityBulkUploadStats'
required:
- errors
- stats
description: Bulk upload successful
'413':
description: File too large
summary: Bulk upsert asset criticality records
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/asset_criticality/list:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/asset_criticality/list</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
List asset criticality records, paging, sorting and filtering as needed.'
operationId: FindAssetCriticalityRecords
parameters:
- description: The field to sort by.
in: query
name: sort_field
required: false
schema:
enum:
- id_value
- id_field
- criticality_level
- '@timestamp'
type: string
- description: The order to sort by.
in: query
name: sort_direction
required: false
schema:
enum:
- asc
- desc
type: string
- description: The page number to return.
in: query
name: page
required: false
schema:
minimum: 1
type: integer
- description: The number of records to return per page.
in: query
name: per_page
required: false
schema:
maximum: 1000
minimum: 1
type: integer
- description: The kuery to filter by.
in: query
name: kuery
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
example:
page: 1
per_page: 10
records:
- '@timestamp': '2024-08-02T14:40:35.705Z'
asset:
criticality: medium_impact
criticality_level: medium_impact
host:
asset:
criticality: medium_impact
name: my_other_host
id_field: host.name
id_value: my_other_host
- '@timestamp': '2024-08-02T11:15:34.290Z'
asset:
criticality: high_impact
criticality_level: high_impact
host:
asset:
criticality: high_impact
name: my_host
id_field: host.name
id_value: my_host
total: 2
type: object
properties:
page:
minimum: 1
type: integer
per_page:
maximum: 1000
minimum: 1
type: integer
records:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecord'
type: array
total:
minimum: 0
type: integer
required:
- records
- page
- per_page
- total
description: Successfully retrieved asset criticality records
summary: List asset criticality records
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/engine/delete:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/engine/delete</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Deletes the Privilege Monitoring Engine and optionally removes all associated privileged user data.'
operationId: DeleteMonitoringEngine
parameters:
- description: Whether to delete all the privileged user data
in: query
name: data
required: false
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
examples:
DeleteMonitoringEngineResponse:
summary: Engine deleted successfully
value:
deleted: true
schema:
type: object
properties:
deleted:
type: boolean
required:
- deleted
description: Successful response
summary: Delete the Privilege Monitoring Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/engine/disable:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/engine/disable</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Disables the Privilege Monitoring Engine, stopping all monitoring activity without removing data.'
operationId: DisableMonitoringEngine
responses:
'200':
content:
application/json:
examples:
DisableMonitoringEngineResponse:
summary: Engine disabled successfully
value:
status: disabled
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoringEngineDescriptor'
description: Successful response
summary: Disable the Privilege Monitoring Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/engine/init:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/engine/init</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Initializes the Privilege Monitoring Engine, setting up the required resources and starting the engine.'
operationId: InitMonitoringEngine
responses:
'200':
content:
application/json:
examples:
InitMonitoringEngineResponse:
summary: Engine initialized successfully
value:
status: started
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoringEngineDescriptor'
description: Successful response
'500':
content:
application/json:
examples:
InitMonitoringEngineError:
summary: Internal server error during engine initialization
value:
error:
message: Failed to initialize monitoring engine
status: error
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoringEngineDescriptor'
description: Internal Server Error
summary: Initialize the Privilege Monitoring Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/engine/schedule_now:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/engine/schedule_now</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Schedules the Privilege Monitoring Engine to run as soon as possible, triggering an immediate monitoring cycle.'
operationId: ScheduleMonitoringEngine
responses:
'200':
content:
application/json:
examples:
ScheduleMonitoringEngineResponse:
summary: Engine scheduled successfully
value:
success: true
schema:
type: object
properties:
success:
description: Indicates the scheduling was successful
type: boolean
description: Successful response
'409':
content:
application/json:
examples:
ScheduleMonitoringEngineConflict:
summary: Engine is already running
value:
message: Monitoring engine is already running
schema:
type: object
properties:
message:
description: Error message indicating the engine is already running
type: string
description: Conflict - Monitoring engine is already running
summary: Schedule the Privilege Monitoring Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/privileges/health:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/privileges/health</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Returns the current health status of the Privilege Monitoring Engine, including engine status, error details, and user count statistics.'
operationId: PrivMonHealth
responses:
'200':
content:
application/json:
examples:
PrivMonHealthResponse:
summary: Healthy privilege monitoring engine
value:
status: started
users:
current_count: 42
max_allowed: 1000
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
required:
- status
status:
$ref: '#/components/schemas/Security_Entity_Analytics_API_PrivilegeMonitoringEngineStatus'
users:
description: User statistics for privilege monitoring
type: object
properties:
current_count:
description: Current number of privileged users being monitored
type: integer
max_allowed:
description: Maximum number of privileged users allowed to be monitored
type: integer
required:
- current_count
- max_allowed
required:
- status
description: Successful response
summary: Health check on Privilege Monitoring
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/privileges/privileges:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/privileges/privileges</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Check if the current user has all required permissions for Privilege Monitoring'
operationId: PrivMonPrivileges
responses:
'200':
content:
application/json:
examples:
PrivMonPrivilegesResponse:
summary: Privileges check response
value:
has_all_required: true
privileges:
elasticsearch:
index:
.entity_analytics.monitoring.user-default:
read: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityAnalyticsPrivileges'
description: Successful response
summary: Run a privileges check on Privilege Monitoring
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/users:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/users</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Creates a new privileged user to be monitored by the Privilege Monitoring Engine.'
operationId: CreatePrivMonUser
requestBody:
content:
application/json:
examples:
CreatePrivMonUserRequest:
summary: Create a monitored user
value:
entity_analytics_monitoring:
labels:
- field: department
source: api
value: IT
user:
name: john.doe
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_UserName'
required: true
responses:
'200':
content:
application/json:
examples:
CreatePrivMonUserResponse:
summary: Created monitored user
value:
'@timestamp': '2026-01-28T12:00:00.000Z'
entity_analytics_monitoring:
labels:
- field: department
source: api
value: IT
event:
ingested: '2026-01-28T12:00:00.000Z'
id: user-abc-123
user:
is_privileged: true
name: john.doe
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoredUserDoc'
description: User created successfully
summary: Create a new monitored user
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/users/_csv:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/users/_csv</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Bulk upserts privileged users by uploading a CSV file. Returns per-row errors and aggregate upload statistics.'
operationId: PrivmonBulkUploadUsersCSV
requestBody:
content:
multipart/form-data:
examples:
PrivmonBulkUploadUsersCSVRequest:
summary: CSV file with privileged users
value:
file: 'username,is_privileged
john.doe,true
jane.smith,true
'
schema:
type: object
properties:
file:
description: The CSV file to upload.
format: binary
type: string
required:
- file
responses:
'200':
content:
application/json:
examples:
PrivmonBulkUploadUsersCSVResponse:
summary: Bulk upload response with mixed results
value:
errors:
- index: 1
message: Invalid monitored field
username: john.doe
stats:
failedOperations: 1
successfulOperations: 1
totalOperations: 2
uploaded: 2
schema:
type: object
properties:
errors:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_PrivmonUserCsvUploadErrorItem'
type: array
stats:
$ref: '#/components/schemas/Security_Entity_Analytics_API_PrivmonUserCsvUploadStats'
required:
- errors
- stats
description: Bulk upload successful
'413':
description: File too large
summary: Upsert multiple monitored users via CSV upload
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/users/{id}:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/users/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Removes a privileged user from monitoring by their document ID.'
operationId: DeletePrivMonUser
parameters:
- description: The document ID of the monitored user to delete
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
DeletePrivMonUserResponse:
summary: User deleted successfully
value:
acknowledged: true
message: User deleted successfully
schema:
type: object
properties:
acknowledged:
description: Indicates if the deletion was successful
type: boolean
message:
description: A message providing additional information about the deletion status
type: string
required:
- success
description: User deleted successfully
summary: Delete a monitored user
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
put:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb put">put</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/users/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Updates the details of an existing monitored privileged user by their document ID.'
operationId: UpdatePrivMonUser
parameters:
- description: The document ID of the monitored user to update
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
UpdatePrivMonUserRequest:
summary: Update a monitored user
value:
entity_analytics_monitoring:
labels:
- field: department
source: api
value: Security
user:
is_privileged: true
name: john.doe
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoredUserUpdateDoc'
required: true
responses:
'200':
content:
application/json:
examples:
UpdatePrivMonUserResponse:
summary: Updated monitored user
value:
'@timestamp': '2026-01-28T12:00:00.000Z'
entity_analytics_monitoring:
labels:
- field: department
source: api
value: Security
event:
ingested: '2026-01-28T12:00:00.000Z'
id: user-abc-123
user:
is_privileged: true
name: john.doe
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoredUserDoc'
description: User updated successfully
summary: Update a monitored user
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/monitoring/users/list:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/entity_analytics/monitoring/users/list</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manag
# --- truncated at 32 KB (155 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-security-entity-analytics-api-api-openapi.yml