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:**
delete /s/{space_id}/api/asset_criticality
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:**
get /s/{space_id}/api/asset_criticality
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:**
post /s/{space_id}/api/asset_criticality
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:**
post /s/{space_id}/api/asset_criticality/bulk
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:**
get /s/{space_id}/api/asset_criticality/list
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:**
delete /s/{space_id}/api/entity_analytics/monitoring/engine/delete
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:**
post /s/{space_id}/api/entity_analytics/monitoring/engine/disable
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:**
post /s/{space_id}/api/entity_analytics/monitoring/engine/init
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:**
post /s/{space_id}/api/entity_analytics/monitoring/engine/schedule_now
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:**
get /s/{space_id}/api/entity_analytics/monitoring/privileges/health
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:**
get /s/{space_id}/api/entity_analytics/monitoring/privileges/privileges
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:**
post /s/{space_id}/api/entity_analytics/monitoring/users
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:**
post /s/{space_id}/api/entity_analytics/monitoring/users/_csv
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:**
delete /s/{space_id}/api/entity_analytics/monitoring/users/{id}
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:**
put /s/{space_id}/api/entity_analytics/monitoring/users/{id}
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:**
get /s/{space_id}/api/entity_analytics/monitoring/users/list
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Returns a list of all privileged users currently being monitored. Supports optional KQL filtering.'
operationId: ListPrivMonUsers
parameters:
- description: KQL query to filter the list of monitored users
in: query
name: kql
required: false
schema:
type: string
responses:
'200':
content:
application/json:
examples:
ListPrivMonUsersResponse:
summary: List of monitored users
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
- '@timestamp': '2026-01-15T09:00:00.000Z'
entity_analytics_monitoring:
labels:
- field: department
source: csv
value: Security
event:
ingested: '2026-01-15T09:00:00.000Z'
id: user-def-456
user:
is_privileged: true
name: jane.smith
schema:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoredUserDoc'
type: array
description: List of monitored users
summary: List all monitored users
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/privileged_user_monitoring/pad/install:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_analytics/privileged_user_monitoring/pad/install
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Installs the privileged access detection integration package and sets up the associated ML modules required for the Entity Analytics privileged user monitoring experience.'
operationId: InstallPrivilegedAccessDetectionPackage
responses:
'200':
content:
application/json:
examples:
InstallPrivilegedAccessDetectionPackageResponse:
summary: Package installed successfully
value:
message: Privileged access detection package installed successfully
schema:
type: object
properties:
message:
type: string
required:
- message
description: Successful response
summary: Installs the privileged access detection package for the Entity Analytics privileged user monitoring experience
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/privileged_user_monitoring/pad/status:
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_analytics/privileged_user_monitoring/pad/status
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Returns the installation and ML module setup status of the privileged access detection package, along with the state of each associated ML job.'
operationId: GetPrivilegedAccessDetectionPackageStatus
responses:
'200':
content:
application/json:
examples:
GetPrivilegedAccessDetectionPackageStatusResponse:
summary: Package fully installed and running
value:
jobs:
- description: Detects high-risk login patterns
job_id: pad-high-risk-login
state: opened
- description: Detects privilege escalation events
job_id: pad-privilege-escalation
state: opened
ml_module_setup_status: complete
package_installation_status: complete
schema:
type: object
properties:
jobs:
items:
type: object
properties:
description:
type: string
job_id:
type: string
state:
enum:
- closing
- closed
- opened
- failed
- opening
type: string
required:
- job_id
- state
type: array
ml_module_setup_status:
enum:
- complete
- incomplete
type: string
package_installation_status:
enum:
- complete
- incomplete
type: string
required:
- package_installation_status
- ml_module_setup_status
- jobs
description: Privileged access detection status retrieved
summary: Gets the status of the privileged access detection package for the Entity Analytics privileged user monitoring experience
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/watchlists:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_analytics/watchlists
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Creates a new entity analytics watchlist with an optional set of entity sources. Watchlists apply a risk score modifier to matched entities.'
operationId: CreateWatchlist
requestBody:
content:
application/json:
examples:
CreateWatchlistRequest:
summary: Create watchlist request
value:
description: High risk vendor watchlist
managed: false
name: High Risk Vendors
riskModifier: 1.5
CreateWatchlistWithSourcesRequest:
summary: Create watchlist with entity sources
value:
description: High risk vendor watchlist
entitySources:
- enabled: true
identifierField: user.name
indexPattern: my-sync-index
name: My User Index Source
type: index
managed: false
name: High Risk Vendors
riskModifier: 1.5
schema:
type: object
properties:
description:
description: Description of the watchlist
type: string
entitySources:
description: Optional entity sources to create and link to the watchlist
items:
additionalProperties: false
type: object
properties:
enabled:
type: boolean
filter:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Filter'
identifierField:
description: Field used to query the entity store for index-type sources
type: string
indexPattern:
type: string
integrationName:
description: Required when type is entity_analytics_integration. One of entityanalytics_okta, entityanalytics_ad.
type: string
matchers:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Matcher'
type: array
name:
type: string
queryRule:
description: KQL query used to filter data from the provided index patterns
type: string
range:
$ref: '#/components/schemas/Security_Entity_Analytics_API_DateRange'
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntitySourceType'
required:
- type
- name
type: array
managed:
description: Indicates if the watchlist is managed by the system
type: boolean
name:
description: Unique name for the watchlist
type: string
riskModifier:
description: Risk score modifier associated with the watchlist
maximum: 2
minimum: 0
type: number
required:
- name
- riskModifier
required: true
responses:
'200':
content:
application/json:
examples:
CreateWatchlistResponse:
summary: Created watchlist
value:
createdAt: '2026-01-28T12:00:00.000Z'
description: High risk vendor watchlist
id: watchlist-123
managed: false
name: High Risk Vendors
riskModifier: 1.5
updatedAt: '2026-01-28T12:00:00.000Z'
schema:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistObject'
- type: object
properties:
entitySources:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoringEntitySource'
type: array
description: Watchlist created successfully
summary: Create a new watchlist
tags:
- Security Entity Analytics API
x-state: Technical Preview
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/watchlists/{id}:
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_analytics/watchlists/{id}
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Retrieves the details of an entity analytics watchlist by its unique identifier.'
operationId: GetWatchlist
parameters:
- description: Unique ID of the watchlist
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
GetWatchlistResponse:
summary: Watchlist details
value:
createdAt: '2026-01-28T12:00:00.000Z'
description: High risk vendor watchlist
id: watchlist-123
managed: false
name: High Risk Vendors
riskModifier: 1.5
updatedAt: '2026-02-18T12:00:00.000Z'
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistObject'
description: Watchlist details
summary: Get a watchlist by ID
tags:
- Security Entity Analytics API
x-state: Technical Preview
x-metaTags:
- content: Kibana
name: product_name
put:
description: '**Spaces method and path for this operation:**
put /s/{space_id}/api/entity_analytics/watchlists/{id}
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Updates the name, description, risk modifier, or managed status of an existing entity analytics watchlist.'
operationId: UpdateWatchlist
parameters:
- description: The ID of the watchlist to update
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
UpdateWatchlistRequest:
summary: Update watchlist request
value:
description: High risk vendor watchlist
managed: false
name: High Risk Vendors
riskModifier: 1.5
schema:
type: object
properties:
description:
description: Description of the watchlist
type: string
managed:
description: Indicates if the watchlist is managed by the system
type: boolean
name:
description: Unique name of the watchlist
type: string
riskModifier:
description: Risk score modifier associated with the watchlist
maximum: 2
minimum: 0
type: number
required:
- name
- riskModifier
required: true
responses:
'200':
content:
application/json:
examples:
UpdateWatchlistResponse:
summary: Updated watchlist
value:
createdAt: '2026-01-28T12:00:00.000Z'
description: High risk vendor watchlist
id: watchlist-123
managed: false
name: High Risk Vendors
riskModifier: 1.5
updatedAt: '2026-02-18T12:00:00.000Z'
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistObject'
description: Watchlist updated successfully
summary: Update an existing watchlist
tags:
- Security Entity Analytics API
x-state: Technical Preview
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/watchlists/{watchlist_id}/csv_upload:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_analytics/watchlists/{watchlist_id}/csv_upload
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Uploads a CSV file to add entities to a watchlist. The CSV must contain a header row
with a "type" column (user, host, service, or generic) and one or more ECS identity
fields (e.g. "user.name", "host.hostname") used to match entities in the entity store.
Matched entities are added to the watchlist and their `entity.attributes.watchlists`
field is updated in the entity store.
Each row will match up to 10,000 entities.
'
operationId: UploadWatchlistCsv
parameters:
- description: The ID of the watchlist to add entities to
example: high-risk-vendors
in: path
name: watchlist_id
required: true
schema:
type: string
requestBody:
content:
multipart/form-data:
examples:
csvUpload:
summary: CSV file with user entities
value:
file: 'type,user.name
user,john.doe
user,jane.smith
'
schema:
type: object
properties:
file:
description: The CSV file to upload.
format: binary
type: string
required:
- file
required: true
responses:
'200':
content:
application/json:
examples:
CsvUploadResponse:
summary: CSV upload response with mixed results
value:
failed: 1
items:
- matchedEntities: 1
status: success
- error: Invalid entity type
matchedEntities: 0
status: failure
- matchedEntities: 0
status: unmatched
successful: 1
total: 3
unmatched: 1
schema:
type: object
properties:
failed:
description: Number of rows that failed to process
example: 1
type: integer
items:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistCsvUploadResponseItem'
type: array
successful:
description: Number of rows that matched at least one entity
example: 1
type: integer
total:
description: Total number of rows processed
example: 3
type: integer
unmatched:
description: Number of rows that matched no entities
example: 1
type: integer
required:
- successful
- failed
- total
- unmatched
- items
description: Upload successful
'413':
description: File too large
summary: Upload a CSV file to add entities to a watchlist
tags:
- Security Entity Analytics API
x-state: Technical Preview
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/watchlists/{watchlist_id}/entities/assign:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_analytics/watchlists/{watchlist_id}/entities/assign
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Assigns the provided entities to the specified watchlist using a "manual" source label.
The entities must already exist in the entity store.
If an entity is already on the watchlist, no new document is created — the "manual" label
is added to its existing source labels instead.
'
operationId: AssignWatchlistEntities
parameters:
- description: The ID of the watchlist to add entities to
example: high-risk-vendors
in: path
name: watchlist_id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
assignEntities:
summary: Assign two entities to a watchlist
value:
euids:
- user:john.doe
- host:web-01
schema:
type: object
properties:
euids:
description: The EUIDs of the entities to assign
example:
- user:john.doe
- host:web-01
items:
type: string
type: array
required:
- euids
required: true
responses:
'200':
content:
application/json:
examples:
assignEntitiesResponse:
summary: Successful assignment of two entities
value:
failed: 0
items:
- euid: user:john.doe
status: success
- euid: host:web-01
status: not_found
not_found: 1
successful: 1
total: 2
schema:
type: object
properties:
failed:
description: Number of entities that failed to process
example: 0
type: integer
items:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistEntityAssignResponseItem'
type: array
not_found:
description: Number of entities not found in the entity store
example: 1
type: integer
successful:
description: Number of entities successfully assigned
example: 1
type: integer
total:
description: Total number of entities processed
example: 2
type: integer
required:
- successful
- failed
- not_found
- total
- items
description: Assignment successful
summary: Manually assign entities to a watchlist
tags:
- Security Entity Analytics API
x-state: Technical Preview; added in 9.4.0
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/watchlists/{watchlist_id}/entities/unassign:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_analytics/watchlists/{watchlist_id}/entities/unassign
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Unassigns the provided entities from the specified watchlist.
This only removes the "manual" assignment. If the entity is also
assigned via other sources (for example, index or integration), it will
remain on the watchlist.
'
operationId: UnassignWatchlistEntities
parameters:
- description: The ID of the watchlist to remove entities from
example: high-risk-vendors
in: path
name: watchlist_id
required: true
schema:
type: string
requestBody:
content:
application/json:
examples:
unassignEntities:
summary: Unassign two entities from a watchlist
value:
euids:
- user:john.doe
- host:web-01
schema:
type: object
properties:
euids:
description: The EUIDs of the entities to unassign
example:
- user:john.doe
- host:web-01
items:
type: string
type: array
required:
- euids
required: true
responses:
'200':
content:
application/json:
examples:
unassignEntitiesResponse:
summary: Successful unassignment of two entities
value:
failed: 0
items:
- euid: user:john.doe
status: success
- euid: host:web-01
status: not_found
not_found: 1
successful: 1
total: 2
schema:
type: object
properties:
failed:
description: Number of entities that failed to process
example: 0
type: integer
items:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistEntityUnassignResponseItem'
type: array
not_found:
description: Number of entities not found in the manual watchlist assignment
example: 1
type: integer
successful:
description: Number of entities successfully unassigned
example: 1
type: integer
total:
description: Total number of entities processed
example: 2
type: integer
required:
- successful
- failed
- not_found
- total
- items
description: Unassignment successful
summary: Manually unassign entities from a watchlist
tags:
- Security Entity Analytics API
x-state: Technical Preview; added in 9.4.0
x-metaTags:
- content: Kibana
name: product_name
/api/entity_analytics/watchlists/list:
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_analytics/watchlists/list
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Returns a list of all entity analytics watchlists.'
operationId: ListWatchlists
responses:
'200':
content:
application/json:
examples:
ListWatchlistsResponse:
summary: List of watchlists
value:
- createdAt: '2026-01-28T12:00:00.000Z'
description: High risk vendor watchlist
id: watchlist-123
managed: false
name: High Risk Vendors
riskModifier: 1.5
updatedAt: '2026-02-18T12:00:00.000Z'
- createdAt: '2026-01-10T09:30:00.000Z'
description: Privileged user monitoring watchlist
id: watchlist-456
managed: true
name: Privileged Accounts
riskModifier: 2
updatedAt: '2026-02-01T15:45:00.000Z'
schema:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_WatchlistObject'
type: array
description: List of watchlists
summary: List all watchlists
tags:
- Security Entity Analytics API
x-state: Technical Preview
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/enable:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_store/enable
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Initialize the entire Entity Store, creating engines for all or specified entity types.'
operationId: InitEntityStore
requestBody:
content:
application/json:
schema:
type: object
properties:
delay:
default: 1m
description: The delay before the transform will run.
pattern: '[smdh]$'
type: string
docsPerSecond:
default: -1
description: The number of documents per second to process.
type: integer
enrichPolicyExecutionInterval:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Interval'
entityTypes:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
fieldHistoryLength:
default: 10
description: The number of historical values to keep for each field.
type: integer
filter:
type: string
frequency:
default: 1m
description: The frequency at which the transform will run.
pattern: '[smdh]$'
type: string
indexPattern:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IndexPattern'
lookbackPeriod:
default: 3h
description: The amount of time the transform looks back to calculate the aggregations.
pattern: '[smdh]$'
type: string
maxPageSearchSize:
default: 500
description: The initial page size to use for the composite aggregation of each checkpoint.
type: integer
timeout:
default: 180s
description: The timeout for initializing the aggregating transform.
pattern: '[smdh]$'
type: string
timestampField:
default: '@timestamp'
description: The field to use as the timestamp.
type: string
description: Configuration for the entity store initialization.
required: true
responses:
'200':
content:
application/json:
examples:
initEntityStoreExample:
description: The Entity Store was successfully initialized, creating host and user engines in the installing state.
summary: Entity Store initialized with host and user engines
value:
engines:
- delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: installing
timeout: 180s
timestampField: '@timestamp'
type: host
- delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: installing
timeout: 180s
timestampField: '@timestamp'
type: user
succeeded: true
schema:
type: object
properties:
engines:
description: The engine descriptors created during initialization.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
type: array
succeeded:
description: Whether the Entity Store was initialized successfully.
type: boolean
description: Successful response
'400':
description: Invalid request
summary: Initialize the Entity Store
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/engines:
delete:
operationId: DeleteEntityEngines
parameters:
- description: The entity type of the engine ('user', 'host', 'service', 'generic').
examples:
hostAndService:
value: host,service
in: query
name: entityTypes
required: false
schema:
description: Array of engine types to delete. Empty by default, which results in all the engines being deleted.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
- description: Control flag to also delete the entity data.
in: query
name: delete_data
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
examples:
deleteEntityEnginesExample:
description: Example response after deleting 'host' engine
value:
deleted:
- host
still_running:
- generic
- user
- service
schema:
type: object
properties:
deleted:
description: Entity types whose engines were successfully deleted.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
still_running:
description: Entity types whose engines are still running.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
description: Successful response
summary: Delete Entity Engines
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
description: '**Spaces method and path for this operation:**
delete /s/{space_id}/api/entity_store/engines
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.'
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_store/engines
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a list of all installed entity engines and their current status.'
operationId: ListEntityEngines
responses:
'200':
content:
application/json:
examples:
listEntityEnginesExample:
description: Returns a list with one running host engine and one stopped user engine.
summary: Two engines installed
value:
count: 2
engines:
- delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: started
timeout: 180s
timestampField: '@timestamp'
type: host
- delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: stopped
timeout: 180s
timestampField: '@timestamp'
type: user
schema:
type: object
properties:
count:
description: The total number of entity engines.
type: integer
engines:
description: An array of engine descriptors.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
type: array
description: Successful response
summary: List the Entity Engines
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/engines/{entityType}:
delete:
operationId: DeleteEntityEngine
parameters:
- description: The entity type of the engine (either 'user' or 'host').
examples:
host:
value: host
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
- description: Control flag to also delete the entity data.
in: query
name: delete_data
required: false
schema:
type: boolean
- deprecated: true
description: Control flag to also delete the entity data.
in: query
name: data
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
examples:
deleteEntityEngineExample:
description: Example response after deleting 'host' engine
value:
deleted: true
schema:
type: object
properties:
deleted:
description: Whether the engine was successfully deleted.
type: boolean
description: Successful response
summary: Delete the Entity Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
description: '**Spaces method and path for this operation:**
delete /s/{space_id}/api/entity_store/engines/{entityType}
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.'
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_store/engines/{entityType}
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the engine descriptor for a specific entity type, including its configuration and current status.'
operationId: GetEntityEngine
parameters:
- description: The entity type of the engine.
example: host
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
responses:
'200':
content:
application/json:
examples:
getEntityEngineExample:
description: Returns the engine descriptor for a host engine that is currently running with default settings.
summary: A running host engine
value:
delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: started
timeout: 180s
timestampField: '@timestamp'
type: host
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
description: Successful response
summary: Get an Entity Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/engines/{entityType}/init:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_store/engines/{entityType}/init
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Initialize a single entity engine for the specified entity type.'
operationId: InitEntityEngine
parameters:
- description: The entity type of the engine.
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
requestBody:
content:
application/json:
schema:
type: object
properties:
delay:
default: 1m
description: The delay before the transform will run.
pattern: '[smdh]$'
type: string
docsPerSecond:
default: -1
description: The number of documents per second to process.
type: integer
enrichPolicyExecutionInterval:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Interval'
fieldHistoryLength:
default: 10
description: The number of historical values to keep for each field.
type: integer
filter:
type: string
frequency:
default: 1m
description: The frequency at which the transform will run.
pattern: '[smdh]$'
type: string
indexPattern:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IndexPattern'
lookbackPeriod:
default: 3h
description: The amount of time the transform looks back to calculate the aggregations.
pattern: '[smdh]$'
type: string
maxPageSearchSize:
default: 500
description: The initial page size to use for the composite aggregation of each checkpoint.
type: integer
timeout:
default: 180s
description: The timeout for initializing the aggregating transform.
pattern: '[smdh]$'
type: string
timestampField:
default: '@timestamp'
description: The field to use as the timestamp for the entity type.
type: string
description: Schema for the engine initialization
required: true
responses:
'200':
content:
application/json:
examples:
initEntityEngineExample:
description: A host engine was successfully initialized and is now in the installing state.
summary: Host engine initialized
value:
delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 3h
status: installing
timeout: 180s
timestampField: '@timestamp'
type: host
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
description: Successful response
'400':
description: Invalid request
summary: Initialize an Entity Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/engines/{entityType}/start:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_store/engines/{entityType}/start
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Start a previously stopped entity engine, resuming transform processing for the given entity type.'
operationId: StartEntityEngine
parameters:
- description: The entity type of the engine to start.
example: host
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
responses:
'200':
content:
application/json:
examples:
startEntityEngineExample:
description: The engine was successfully started and is now processing data.
summary: Engine started successfully
value:
started: true
schema:
type: object
properties:
started:
description: Whether the engine was successfully started.
type: boolean
description: Successful response
summary: Start an Entity Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/engines/{entityType}/stop:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_store/engines/{entityType}/stop
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Stop a running entity engine, pausing transform processing for the given entity type.'
operationId: StopEntityEngine
parameters:
- description: The entity type of the engine to stop.
example: host
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
responses:
'200':
content:
application/json:
examples:
stopEntityEngineExample:
description: The engine was successfully stopped and is no longer processing data.
summary: Engine stopped successfully
value:
stopped: true
schema:
type: object
properties:
stopped:
description: Whether the engine was successfully stopped.
type: boolean
description: Successful response
summary: Stop an Entity Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/engines/apply_dataview_indices:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/entity_store/engines/apply_dataview_indices
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Synchronize data view index patterns to all running entity engines so that newly added indices are picked up by the transforms.'
operationId: ApplyEntityEngineDataviewIndices
responses:
'200':
content:
application/json:
examples:
applyDataviewIndicesExample:
description: All running engines were successfully updated with the current data view index patterns.
summary: All engines updated
value:
result:
- changes:
indexPatterns:
- logs-*
- filebeat-*
- auditbeat-*
type: host
- changes:
indexPatterns:
- logs-*
- filebeat-*
- auditbeat-*
type: user
success: true
schema:
type: object
properties:
result:
description: Per-engine update results.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDataviewUpdateResult'
type: array
success:
description: Whether all engines updated successfully.
type: boolean
description: Successful response
'207':
content:
application/json:
examples:
partialSuccessExample:
description: The host engine was updated but the user engine failed due to insufficient privileges.
summary: One engine failed
value:
errors:
- 'Failed to update user engine: insufficient privileges'
result:
- changes:
indexPatterns:
- logs-*
- filebeat-*
type: host
success: false
schema:
type: object
properties:
errors:
description: Error messages for engines that failed to update.
items:
type: string
type: array
result:
description: Per-engine update results for engines that succeeded.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDataviewUpdateResult'
type: array
success:
description: Always `false` for a partial success.
type: boolean
description: Partial successful response
'500':
content:
application/json:
examples:
serverErrorExample:
description: An unexpected error occurred while applying data view indices.
summary: Internal server error
value:
body: An internal error occurred while updating engine indices
statusCode: 500
schema:
type: object
properties:
body:
description: Error message.
type: string
statusCode:
description: HTTP status code.
type: number
description: Error response
summary: Apply DataView indices to all installed engines
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/entities/{entityType}:
delete:
description: "**Spaces method and path for this operation:**\n\ndelete /s/{space_id}/api/entity_store/entities/{entityType}
\n\nRefer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.\n\nDelete a single entity in Entity Store.\nThe entity will be immediately deleted from the latest index. It will remain available in historical snapshots if it has been snapshotted. The delete operation does not prevent the entity from being recreated if it is observed again in the future. \n"
operationId: DeleteSingleEntity
parameters:
- example: user
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
requestBody:
content:
application/json:
schema:
type: object
properties:
id:
description: Identifier of the entity to be deleted, commonly entity.id value.
example: arn:aws:iam::123456789012:user/jane.doe
type: string
required:
- id
description: Schema for the deleting entity
required: true
responses:
'200':
content:
application/json:
examples:
deleteEntityExample:
description: The entity was found and successfully removed from the latest index.
summary: Entity deleted
value:
deleted: true
schema:
type: object
properties:
deleted:
description: Whether the entity was successfully deleted.
type: boolean
description: Successful response. Entity deleted.
'404':
description: Entity Not Found. No entity with this ID and Type exists.
'503':
description: Operation on an uninitialized Engine or in a cluster without CRUD API Enabled
summary: Delete an entity in Entity Store
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
put:
description: '**Spaces method and path for this operation:**
put /s/{space_id}/api/entity_store/entities/{entityType}
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Update or create an entity in Entity Store.
If the specified entity already exists, it is updated with the provided values. If the entity does not exist, a new one is created. By default, only the following fields can be updated: * `entity.attributes.*` * `entity.lifecycle.*` * `entity.behavior.*` To update other fields, set the `force` query parameter to `true`. > info > Some fields always retain the first observed value. Updates to these fields will not appear in the final index.
> Due to technical limitations, not all updates are guaranteed to appear in the final list of observed values.
> Due to technical limitations, create is an async operation. The time for a document to be present in the > final index depends on the entity store transform and usually takes more than 1 minute.
'
operationId: UpsertEntity
parameters:
- example: user
in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
- description: When true, allows updating protected fields.
in: query
name: force
required: false
schema:
default: false
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
description: Schema for the updating a single entity
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
description: Entity updated or created
'403':
description: Operation on a restricted field
'409':
description: Conflict. The entity was updated while another update was happening in ElasticSearch
'503':
description: Operation on an uninitialized Engine or in a cluster without CRUD API Enabled
summary: Upsert an entity in Entity Store
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/entities/bulk:
put:
description: '**Spaces method and path for this operation:**
put /s/{space_id}/api/entity_store/entities/bulk
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Update or create many entities in Entity Store.
If the specified entity already exists, it is updated with the provided values. If the entity does not exist, a new one is created.
The creation is asynchronous. The time for a document to be present in the final index depends on the entity store transform and usually takes more than 1 minute.
'
operationId: UpsertEntitiesBulk
parameters:
- description: When true, allows updating protected fields.
in: query
name: force
required: false
schema:
default: false
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntitiesContainer'
description: Schema for the updating many entities
required: true
responses:
'200':
description: Entities updated or created
'403':
description: Operation on a restricted field
'503':
description: Operation on an uninitialized Engine or in a cluster without CRUD API Enabled
summary: Upsert many entities in Entity Store
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/entities/list:
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_store/entities/list
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
List entities records, paging, sorting and filtering as needed.'
operationId: ListEntities
parameters:
- description: Field to sort results by.
example: entity.name
in: query
name: sort_field
required: false
schema:
type: string
- description: Sort order.
in: query
name: sort_order
required: false
schema:
enum:
- asc
- desc
type: string
- description: Page number to return (1-indexed).
example: 1
in: query
name: page
required: false
schema:
minimum: 1
type: integer
- description: Number of entities per page.
example: 10
in: query
name: per_page
required: false
schema:
maximum: 10000
minimum: 1
type: integer
- description: An ES query to filter by.
in: query
name: filterQuery
required: false
schema:
type: string
- description: Entity types to include in the results.
in: query
name: entity_types
required: true
schema:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
responses:
'200':
content:
application/json:
schema:
type: object
properties:
inspect:
$ref: '#/components/schemas/Security_Entity_Analytics_API_InspectQuery'
page:
description: Current page number.
minimum: 1
type: integer
per_page:
description: Number of entities per page.
maximum: 1000
minimum: 1
type: integer
records:
description: The entity records for this page.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
type: array
total:
description: Total number of entities matching the query.
minimum: 0
type: integer
required:
- records
- page
- per_page
- total
description: Entities returned successfully
summary: List Entity Store Entities
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/entity_store/status:
get:
description: '**Spaces method and path for this operation:**
get /s/{space_id}/api/entity_store/status
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the overall Entity Store status and per-engine statuses, optionally including component-level health details.'
operationId: GetEntityStoreStatus
parameters:
- description: If true, returns a detailed status of each engine including all its components.
example: true
in: query
name: include_components
schema:
type: boolean
responses:
'200':
content:
application/json:
examples:
entityStoreRunning:
description: The Entity Store is running with both host and user engines started and using default settings.
summary: Entity Store running with two engines
value:
engines:
- delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: started
timeout: 180s
timestampField: '@timestamp'
type: host
- delay: 1m
fieldHistoryLength: 10
frequency: 1m
indexPattern: ''
lookbackPeriod: 24h
status: started
timeout: 180s
timestampField: '@timestamp'
type: user
status: running
schema:
type: object
properties:
engines:
description: Per-engine status information.
items:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
- type: object
properties:
components:
description: Detailed component-level status. Only included when include_components is true.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineComponentStatus'
type: array
type: array
status:
$ref: '#/components/schemas/Security_Entity_Analytics_API_StoreStatus'
description: The overall status of the Entity Store.
required:
- status
- engines
description: Successful response
summary: Get the status of the Entity Store
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/risk_score/engine/dangerously_delete_data:
delete:
description: '**Spaces method and path for this operation:**
delete /s/{space_id}/api/risk_score/engine/dangerously_delete_data
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Cleaning up the the Risk Engine by removing the indices, mapping and transforms'
operationId: CleanUpRiskEngine
responses:
'200':
content:
application/json:
examples:
CleanUpRiskEngineResponse:
summary: Successful cleanup response
value:
cleanup_successful: true
schema:
type: object
properties:
cleanup_successful:
type: boolean
description: Successful response
'400':
content:
application/json:
examples:
taskManagerUnavailable:
summary: Task manager is unavailable
value:
message: Task Manager is unavailable, but is required by the risk engine. Please enable the taskManager plugin and try again.
status_code: 400
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_TaskManagerUnavailableResponse'
description: Task manager is unavailable
default:
content:
application/json:
examples:
cleanupFailed:
summary: Cleanup failed
value:
cleanup_successful: false
errors:
- error: Risk engine is disabled or deleted already.
seq: 1
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_CleanUpRiskEngineErrorResponse'
description: Unexpected error
summary: Cleanup the Risk Engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/risk_score/engine/saved_object/configure:
patch:
description: '**Spaces method and path for this operation:**
patch /s/{space_id}/api/risk_score/engine/saved_object/configure
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Configuring the Risk Engine Saved Object'
operationId: ConfigureRiskEngineSavedObject
requestBody:
content:
application/json:
examples:
ConfigureRiskEngineSavedObjectRequest:
summary: Configure the risk engine saved object
value:
enable_reset_to_zero: false
exclude_alert_statuses:
- closed
exclude_alert_tags:
- low-priority
filters:
- entity_types:
- host
- user
filter: 'host.name: *'
range:
end: now
start: now-30d
schema:
type: object
properties:
enable_reset_to_zero:
type: boolean
exclude_alert_statuses:
items:
type: string
type: array
exclude_alert_tags:
items:
type: string
type: array
filters:
items:
type: object
properties:
entity_types:
items:
enum:
- host
- user
- service
type: string
type: array
filter:
description: KQL filter string
type: string
required:
- entity_types
- filter
type: array
page_size:
description: 'Number of entities to score per page. Higher values reduce total scoring time by reducing the number of alert-index scans, but cannot exceed the ES|QL result limit (10,000 by default).
'
maximum: 10000
minimum: 100
type: integer
range:
type: object
properties:
end:
type: string
start:
type: string
required: true
responses:
'200':
content:
application/json:
examples:
ConfigureRiskEngineSavedObjectResponse:
summary: Successful configuration response
value:
risk_engine_saved_object_configured: true
schema:
type: object
properties:
risk_engine_saved_object_configured:
type: boolean
description: Successful response
'400':
content:
application/json:
examples:
taskManagerUnavailable:
summary: Task manager is unavailable
value:
message: Task Manager is unavailable, but is required by the risk engine. Please enable the taskManager plugin and try again.
status_code: 400
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_TaskManagerUnavailableResponse'
description: Task manager is unavailable
default:
content:
application/json:
examples:
configureError:
summary: Configure saved object failed
value:
errors:
- error: Internal server error
seq: 1
risk_engine_saved_object_configured: false
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_ConfigureRiskEngineSavedObjectErrorResponse'
description: Unexpected error
summary: Configure the Risk Engine Saved Object
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
/api/risk_score/engine/schedule_now:
post:
description: '**Spaces method and path for this operation:**
post /s/{space_id}/api/risk_score/engine/schedule_now
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality.'
operationId: ScheduleRiskEngineNow
requestBody:
content:
application/json:
examples:
emptyRequest:
summary: No request body
value: {}
schema:
type: object
responses:
'200':
content:
application/json:
examples:
ScheduleRiskEngineNowResponse:
summary: Successful schedule response
value:
success: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_RiskEngineScheduleNowResponse'
description: Successful response
'400':
content:
application/json:
examples:
taskManagerUnavailable:
summary: Task manager is unavailable
value:
message: Task Manager is unavailable, but is required by the risk engine. Please enable the taskManager plugin and try again.
status_code: 400
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_TaskManagerUnavailableResponse'
description: Task manager is unavailable
default:
content:
application/json:
examples:
scheduleNowError:
summary: Schedule now failed
value:
full_error: '{}'
message: Internal server error
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_RiskEngineScheduleNowErrorResponse'
description: Unexpected error
summary: Run the risk scoring engine
tags:
- Security Entity Analytics API
x-metaTags:
- content: Kibana
name: product_name
components:
schemas:
Security_Entity_Analytics_API_HostEntity:
additionalProperties: false
description: An entity record representing a host, stored in the Entity Store latest index.
type: object
properties:
'@timestamp':
description: The time the entity record was last updated.
format: date-time
type: string
asset:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Asset'
additionalProperties: false
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
event:
additionalProperties: false
type: object
properties:
ingested:
description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
additionalProperties: false
description: Elastic Common Schema (ECS) host fields collected on the entity.
type: object
properties:
architecture:
description: Observed CPU architectures.
items:
type: string
type: array
domain:
description: Observed host domains.
items:
type: string
type: array
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
hostname:
description: Observed hostnames.
items:
type: string
type: array
id:
description: Observed host IDs.
items:
type: string
type: array
ip:
description: Observed IP addresses.
items:
type: string
type: array
mac:
description: Observed MAC addresses.
items:
type: string
type: array
name:
description: Primary host name.
type: string
os:
additionalProperties: false
description: Elastic Common Schema (ECS) host.os fields collected on the entity latest index.
type: object
properties:
family:
type: string
full:
type: string
kernel:
type: string
name:
oneOf:
- type: string
- items:
type: string
type: array
platform:
type: string
type:
oneOf:
- type: string
- items:
type: string
type: array
version:
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
type:
description: Observed host types.
items:
type: string
type: array
required:
- name
required:
- entity
Security_Entity_Analytics_API_EntityContainer:
description: A wrapper that pairs an entity type with the entity record to upsert.
type: object
properties:
record:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
description: The entity record to create or update.
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
description: The entity type of the record.
required:
- type
- record
Security_Entity_Analytics_API_AssetCriticalityRecordEcsParts:
type: object
properties:
asset:
type: object
properties:
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
required:
- asset
entity:
type: object
properties:
asset:
type: object
properties:
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
required:
- criticality
id:
type: string
required:
- id
host:
type: object
properties:
asset:
type: object
properties:
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
required:
- criticality
name:
type: string
required:
- name
service:
type: object
properties:
asset:
type: object
properties:
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
required:
- criticality
name:
type: string
required:
- name
user:
type: object
properties:
asset:
type: object
properties:
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
required:
- criticality
name:
type: string
required:
- name
required:
- asset
Security_Entity_Analytics_API_CreateAssetCriticalityRecord:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecordIdParts'
- type: object
properties:
criticality_level:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
required:
- criticality_level
Security_Entity_Analytics_API_Interval:
description: Interval in which enrich policy runs. For example, `"1h"` means the rule runs every hour. Must be less than or equal to half the duration of the lookback period,
example: 1h
pattern: ^[1-9]\d*[smh]$
type: string
Security_Entity_Analytics_API_EntitiesContainer:
description: A collection of entities to upsert in bulk.
type: object
properties:
entities:
description: The entities to create or update.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityContainer'
type: array
required:
- entities
Security_Entity_Analytics_API_ConfigureRiskEngineSavedObjectErrorResponse:
type: object
properties:
errors:
items:
type: object
properties:
error:
type: string
seq:
type: integer
required:
- seq
- error
type: array
risk_engine_saved_object_configured:
example: false
type: boolean
required:
- risk_engine_saved_object_configured
- errors
Security_Entity_Analytics_API_PrivilegeMonitoringEngineStatus:
description: The status of the Privilege Monitoring Engine
enum:
- started
- error
- disabled
- not_installed
type: string
Security_Entity_Analytics_API_WatchlistObject:
example:
createdAt: '2026-01-28T12:00:00.000Z'
description: High risk vendor watchlist
id: watchlist-123
managed: false
name: High Risk Vendors
riskModifier: 1.5
updatedAt: '2026-02-18T12:00:00.000Z'
type: object
properties:
createdAt:
description: Timestamp indicating when the watchlist was created
format: date-time
type: string
description:
description: Description of the watchlist
type: string
entityCount:
description: Number of entities in the watchlist
type: number
entitySourceIds:
description: List of entity source IDs associated with the watchlist
items:
type: string
type: array
id:
description: The unique ID of the watchlist
type: string
managed:
description: Indicates if the watchlist is managed by the system
type: boolean
name:
description: The name of the watchlist
type: string
riskModifier:
description: Risk score modifier associated with the watchlist
type: number
updatedAt:
description: Timestamp indicating when the watchlist was last updated
format: date-time
type: string
required:
- name
- riskModifier
- managed
Security_Entity_Analytics_API_AssetCriticalityBulkUploadStats:
type: object
properties:
failed:
type: integer
successful:
type: integer
total:
type: integer
required:
- successful
- failed
- total
Security_Entity_Analytics_API_TransformStatsMetadata:
description: Statistics from the underlying Elasticsearch transform.
type: object
properties:
delete_time_in_ms:
description: Total time spent deleting documents, in milliseconds.
type: integer
documents_deleted:
description: Total number of documents deleted from the destination index.
type: integer
documents_indexed:
description: Total number of documents written to the destination index.
type: integer
documents_processed:
description: Total number of source documents processed.
type: integer
exponential_avg_checkpoint_duration_ms:
description: Exponential moving average of checkpoint duration, in milliseconds.
type: integer
exponential_avg_documents_indexed:
description: Exponential moving average of documents indexed per checkpoint.
type: integer
exponential_avg_documents_processed:
description: Exponential moving average of documents processed per checkpoint.
type: integer
index_failures:
description: Total number of failed index operations.
type: integer
index_time_in_ms:
description: Total time spent indexing documents, in milliseconds.
type: integer
index_total:
description: Total number of index operations.
type: integer
pages_processed:
description: Number of composite aggregation pages processed.
type: integer
processing_time_in_ms:
description: Total time spent processing results, in milliseconds.
type: integer
processing_total:
description: Total number of processing operations.
type: integer
search_failures:
description: Total number of failed search operations.
type: integer
search_time_in_ms:
description: Total time spent on search queries, in milliseconds.
type: integer
search_total:
description: Total number of search operations.
type: integer
trigger_count:
description: Number of times the transform has been triggered.
type: integer
required:
- pages_processed
- documents_processed
- documents_indexed
- trigger_count
- index_time_in_ms
- index_total
- index_failures
- search_time_in_ms
- search_total
- search_failures
- processing_time_in_ms
- processing_total
- exponential_avg_checkpoint_duration_ms
- exponential_avg_documents_indexed
- exponential_avg_documents_processed
Security_Entity_Analytics_API_EngineComponentResource:
description: The type of Elasticsearch or Kibana resource backing an engine component.
enum:
- entity_engine
- entity_definition
- index
- data_stream
- component_template
- index_template
- ingest_pipeline
- enrich_policy
- task
- transform
- ilm_policy
type: string
Security_Entity_Analytics_API_InspectQuery:
description: Debug information about the Elasticsearch query executed.
type: object
properties:
dsl:
description: Elasticsearch query DSL that was executed.
items:
type: string
type: array
response:
description: Raw Elasticsearch responses.
items:
type: string
type: array
required:
- dsl
- response
Security_Entity_Analytics_API_RiskEngineScheduleNowErrorResponse:
type: object
properties:
full_error:
type: string
message:
type: string
required:
- message
- full_error
Security_Entity_Analytics_API_EngineDataviewUpdateResult:
description: The result of applying data view index changes to a single engine.
type: object
properties:
changes:
description: The changes applied to the engine.
type: object
properties:
indexPatterns:
description: The updated list of index patterns now used by the engine.
items:
type: string
type: array
type:
description: The entity type of the engine that was updated.
type: string
required:
- type
Security_Entity_Analytics_API_ServiceEntity:
additionalProperties: false
description: An entity record representing a service, stored in the Entity Store latest index.
type: object
properties:
'@timestamp':
description: The time the entity record was last updated.
format: date-time
type: string
asset:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Asset'
additionalProperties: false
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
event:
additionalProperties: false
type: object
properties:
ingested:
description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
additionalProperties: false
description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
name:
description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
required:
- name
required:
- entity
Security_Entity_Analytics_API_EntityType:
description: The type of entity.
enum:
- user
- host
- service
- generic
type: string
Security_Entity_Analytics_API_AssetCriticalityLevelsForBulkUpload:
description: The criticality level of the asset for bulk upload. The value `unassigned` is used to indicate that the criticality level is not assigned and is only used for bulk upload.
enum:
- low_impact
- medium_impact
- high_impact
- extreme_impact
- unassigned
type: string
Security_Entity_Analytics_API_RiskEngineScheduleNowResponse:
type: object
properties:
success:
type: boolean
Security_Entity_Analytics_API_AssetCriticalityLevel:
description: The criticality level of the asset.
enum:
- low_impact
- medium_impact
- high_impact
- extreme_impact
type: string
Security_Entity_Analytics_API_PrivmonUserCsvUploadErrorItem:
type: object
properties:
index:
nullable: true
type: integer
message:
type: string
username:
nullable: true
type: string
required:
- message
- index
- username
Security_Entity_Analytics_API_IdField:
enum:
- host.name
- user.name
- service.name
- entity.id
type: string
Security_Entity_Analytics_API_EngineDescriptor:
description: Describes a single entity engine, including its configuration and current status.
type: object
properties:
delay:
default: 1m
description: The delay before the transform processes new data, allowing late-arriving documents to be included.
example: 1m
pattern: '[smdh]$'
type: string
docsPerSecond:
description: Throttle value for the number of documents processed per second. Use -1 for no throttle.
type: integer
error:
description: Present when the engine status is `error`. Describes the failure.
type: object
properties:
action:
description: The lifecycle action that caused the error.
enum:
- init
type: string
message:
description: A human-readable error message.
type: string
required:
- message
- action
fieldHistoryLength:
description: The number of historical values retained per field.
example: 10
type: integer
filter:
description: An optional Kibana Query Language (KQL) filter applied to source documents before aggregation.
example: 'host.name: "my-host"'
type: string
frequency:
default: 1m
description: How often the transform runs.
example: 1m
pattern: '[smdh]$'
type: string
indexPattern:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IndexPattern'
lookbackPeriod:
default: 24h
description: How far back the transform looks when calculating aggregations.
example: 24h
pattern: '[smdh]$'
type: string
status:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineStatus'
timeout:
default: 180s
description: The timeout for initializing the aggregating transform.
example: 180s
pattern: '[smdh]$'
type: string
timestampField:
description: The field used as the timestamp for source documents.
example: '@timestamp'
type: string
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
required:
- type
- indexPattern
- status
- fieldHistoryLength
Security_Entity_Analytics_API_EngineComponentStatus:
description: Status of an individual Elasticsearch or Kibana resource backing an engine.
type: object
properties:
errors:
description: Errors reported by this component, if any.
items:
type: object
properties:
message:
description: Detailed error message.
type: string
title:
description: Short error title.
type: string
type: array
health:
description: The health status of the component.
enum:
- green
- yellow
- red
- unavailable
- unknown
type: string
id:
description: Unique identifier for the component.
type: string
installed:
description: Whether the component is currently installed.
type: boolean
metadata:
$ref: '#/components/schemas/Security_Entity_Analytics_API_TransformStatsMetadata'
resource:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineComponentResource'
required:
- id
- installed
- resource
Security_Entity_Analytics_API_EntitySourceType:
enum:
- index
- entity_analytics_integration
- store
type: string
Security_Entity_Analytics_API_TaskManagerUnavailableResponse:
description: Task manager is unavailable
type: object
properties:
message:
type: string
status_code:
minimum: 400
type: integer
required:
- status_code
- message
Security_Entity_Analytics_API_EntityField:
additionalProperties: false
description: Core entity fields shared across all entity types. The `entity` namespace is a root-level field in the Entity Store latest index.
type: object
properties:
attributes:
additionalProperties: false
description: Boolean flags describing characteristics of the entity.
type: object
properties:
asset:
description: Whether the entity is classified as an asset.
type: boolean
managed:
description: Whether the entity is managed (for example, via a directory service).
type: boolean
mfa_enabled:
description: Whether multi-factor authentication is enabled for the entity.
type: boolean
privileged:
description: Whether the entity has elevated privileges.
type: boolean
behaviors:
additionalProperties: false
description: Boolean flags indicating observed behavioral signals.
type: object
properties:
brute_force_victim:
description: Whether the entity has been targeted by brute-force attacks.
type: boolean
new_country_login:
description: Whether the entity has logged in from a new country.
type: boolean
used_usb_device:
description: Whether the entity has used a USB device.
type: boolean
EngineMetadata:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineMetadata'
id:
description: Unique identifier for this entity.
example: arn:aws:iam::123456789012:user/jane.doe
type: string
lifecycle:
additionalProperties: false
description: Timestamps tracking the entity lifecycle.
type: object
properties:
first_seen:
description: When the entity was first observed.
format: date-time
type: string
last_activity:
description: When the entity last generated activity.
format: date-time
type: string
last_seen:
description: When the entity was last observed.
format: date-time
type: string
name:
description: Human-readable name of the entity.
example: jane.doe
type: string
relationships:
additionalProperties: false
description: Connections between this entity and other entities.
type: object
properties:
accessed_frequently_by:
description: Entity IDs that frequently access this entity.
items:
type: string
type: array
accesses_frequently:
description: Entity IDs this entity accesses frequently.
items:
type: string
type: array
accesses_infrequently:
description: Entity IDs this entity accesses infrequently.
items:
type: string
type: array
communicates_with:
description: Entity IDs this entity communicates with.
items:
type: string
type: array
dependent_of:
description: Entity IDs that depend on this entity.
items:
type: string
type: array
depends_on:
description: Entity IDs this entity depends on.
items:
type: string
type: array
owned_by:
description: Entity IDs that own this entity.
items:
type: string
type: array
owns:
description: Entity IDs owned by this entity.
items:
type: string
type: array
supervised_by:
description: Entity IDs that supervise this entity.
items:
type: string
type: array
supervises:
description: Entity IDs supervised by this entity.
items:
type: string
type: array
risk:
additionalProperties: false
description: Risk scoring information for the entity.
type: object
properties:
calculated_level:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskLevels'
description: Lexical description of the entity's risk.
example: Critical
calculated_score:
description: The raw numeric value of the given entity's risk score.
format: double
type: number
calculated_score_norm:
description: The normalized numeric value of the given entity's risk score. Useful for comparing with other entities.
format: double
maximum: 100
minimum: 0
type: number
source:
description: The source that produced this entity record.
type: string
sub_type:
description: Optional sub-type classification for the entity.
type: string
type:
description: The entity type.
example: user
type: string
required:
- id
Security_Entity_Analytics_API_CleanUpRiskEngineErrorResponse:
type: object
properties:
cleanup_successful:
example: false
type: boolean
errors:
items:
type: object
properties:
error:
type: string
seq:
type: integer
required:
- seq
- error
type: array
required:
- cleanup_successful
- errors
Security_Entity_Analytics_API_AssetCriticalityBulkUploadErrorItem:
type: object
properties:
index:
type: integer
message:
type: string
required:
- message
- index
Security_Entity_Analytics_API_StoreStatus:
description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
- running
- stopped
- error
type: string
Security_Entity_Analytics_API_AssetCriticalityRecordIdParts:
type: object
properties:
id_field:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IdField'
description: The field representing the ID.
example: host.name
id_value:
description: The ID value of the asset.
type: string
required:
- id_value
- id_field
Security_Entity_Analytics_API_UserEntity:
additionalProperties: false
description: An entity record representing a user, stored in the Entity Store latest index.
type: object
properties:
'@timestamp':
description: The time the entity record was last updated.
format: date-time
type: string
asset:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Asset'
additionalProperties: false
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
event:
additionalProperties: false
type: object
properties:
ingested:
description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
additionalProperties: false
description: Elastic Common Schema (ECS) user fields collected on the entity.
type: object
properties:
domain:
description: Observed user domains.
items:
type: string
type: array
email:
description: Observed email addresses.
items:
type: string
type: array
full_name:
description: Observed full names of the user.
items:
type: string
type: array
hash:
description: Observed user hashes.
items:
type: string
type: array
id:
description: Observed user IDs.
items:
type: string
type: array
name:
description: Primary user name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
additionalProperties: false
roles:
description: Observed roles assigned to the user.
items:
type: string
type: array
required:
- name
required:
- entity
Security_Entity_Analytics_API_WatchlistEntityAssignResponseItem:
example:
euid: user:john.doe
status: success
type: object
properties:
error:
description: Error message if the entity failed to process
example: Invalid entity type
type: string
euid:
description: The EUID of the entity
example: user:john.doe
type: string
status:
enum:
- success
- failure
- not_found
example: success
type: string
required:
- euid
- status
Security_Entity_Analytics_API_EngineStatus:
description: The current operational status of an entity engine.
enum:
- installing
- started
- stopped
- updating
- error
type: string
Security_Entity_Analytics_API_EntityRiskLevels:
enum:
- Unknown
- Low
- Moderate
- High
- Critical
type: string
Security_Entity_Analytics_API_EngineMetadata:
additionalProperties: false
description: Internal metadata attached to an entity by the engine that produced it.
type: object
properties:
Type:
description: The engine type that produced this entity record.
type: string
required:
- Type
Security_Entity_Analytics_API_EntityAnalyticsPrivileges:
type: object
properties:
has_all_required:
type: boolean
has_read_permissions:
type: boolean
has_write_permissions:
type: boolean
privileges:
type: object
properties:
elasticsearch:
type: object
properties:
cluster:
additionalProperties:
type: boolean
type: object
index:
additionalProperties:
additionalProperties:
type: boolean
type: object
type: object
kibana:
additionalProperties:
type: boolean
type: object
required:
- elasticsearch
required:
- has_all_required
- privileges
Security_Entity_Analytics_API_RiskScoreInput:
description: A generic representation of a document contributing to a Risk Score.
type: object
properties:
category:
description: The risk category of the risk input document.
example: category_1
type: string
contribution_score:
format: double
type: number
description:
description: A human-readable description of the risk input document.
example: 'Generated from Detection Engine Rule: Malware Prevention Alert'
type: string
entity_id:
description: The EUID of the entity within the graph that generated this alert.
type: string
id:
description: The unique identifier (`_id`) of the original source document
example: 91a93376a507e86cfbf282166275b89f9dbdb1f0be6c8103c6ff2909ca8e1a1c
type: string
index:
description: The unique index (`_index`) of the original source document
example: .internal.alerts-security.alerts-default-000001
type: string
risk_score:
description: The weighted risk score of the risk input document.
format: double
maximum: 100
minimum: 0
type: number
timestamp:
description: The @timestamp of the risk input document.
example: '2017-07-21T17:32:28Z'
type: string
required:
- id
- index
- description
- category
Security_Entity_Analytics_API_GenericEntity:
additionalProperties: false
description: A generic entity record. Maps only the `entity` and `asset` namespaces. Add additional field mappings here as needed.
type: object
properties:
'@timestamp':
description: The time the entity record was last updated.
format: date-time
type: string
asset:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Asset'
additionalProperties: false
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
required:
- entity
Security_Entity_Analytics_API_UpdateableMonitoringEntitySourceProperties:
type: object
properties:
enabled:
type: boolean
filter:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Filter'
identifierField:
description: Field used to query the entity store for index-type sources
type: string
indexPattern:
type: string
integrationName:
type: string
integrations:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Integrations'
matchers:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Matcher'
type: array
name:
type: string
queryRule:
description: KQL query used to filter data from the provided index patterns
type: string
range:
$ref: '#/components/schemas/Security_Entity_Analytics_API_DateRange'
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntitySourceType'
Security_Entity_Analytics_API_MonitoringLabel:
type: object
properties:
field:
type: string
source:
type: string
value:
type: string
required:
- field
- value
- source
Security_Entity_Analytics_API_Entity:
description: An entity record from the Entity Store. The `entity` namespace is a root-level field in the latest index, unlike source logs where it is nested under `host`, `user`, or `service`.
oneOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_UserEntity'
- $ref: '#/components/schemas/Security_Entity_Analytics_API_HostEntity'
- $ref: '#/components/schemas/Security_Entity_Analytics_API_ServiceEntity'
- $ref: '#/components/schemas/Security_Entity_Analytics_API_GenericEntity'
Security_Entity_Analytics_API_AssetCriticalityRecord:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_CreateAssetCriticalityRecord'
- $ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityRecordEcsParts'
- type: object
properties:
'@timestamp':
description: The time the record was created or updated.
example: '2017-07-21T17:32:28Z'
format: date-time
type: string
required:
- '@timestamp'
example:
'@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
Security_Entity_Analytics_API_Filter:
type: object
properties:
kuery:
oneOf:
- type: string
- type: object
Security_Entity_Analytics_API_Integrations:
type: object
properties:
syncData:
description: integrations latest full sync and update syncData
type: object
properties:
lastFullSync:
description: Timestamp of the last full sync from integrations
format: date-time
type: string
lastUpdateProcessed:
description: Timestamp of the last update processed from integrations
format: date-time
type: string
syncMarkerIndex:
description: Index to read latest sync markers from
type: string
Security_Entity_Analytics_API_DateRange:
description: Defines the lookback period for filtering source data by timestamp.
type: object
properties:
end:
description: End of the lookback period (date math or ISO string, e.g. "now")
type: string
start:
description: Start of the lookback period (date math or ISO string, e.g. "now-10d")
type: string
required:
- start
- end
Security_Entity_Analytics_API_Asset:
additionalProperties: false
description: Asset metadata associated with the entity.
type: object
properties:
business_unit:
description: Business unit the asset belongs to.
type: string
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
description: The criticality level assigned to this asset.
nullable: true
environment:
description: Deployment environment (for example, production, staging).
type: string
id:
description: Unique identifier for the asset.
type: string
model:
description: Model name or number.
type: string
name:
description: Human-readable asset name.
type: string
owner:
description: The owner of the asset.
type: string
serial_number:
description: Serial number of the asset.
type: string
vendor:
description: Vendor or manufacturer.
type: string
Security_Entity_Analytics_API_MonitoringEntitySourceProperties:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_UpdateableMonitoringEntitySourceProperties'
- type: object
properties:
managed:
type: boolean
Security_Entity_Analytics_API_Matcher:
type: object
properties:
fields:
items:
type: string
type: array
values:
description: 'Matcher values. Must be either an array of strings (e.g. group or role names) or an array of booleans (e.g. integration-derived flags like privileged_group_member). Mixed types are intentionally not supported for simplicity and predictability.
'
oneOf:
- items:
type: string
type: array
- items:
type: boolean
type: array
required:
- fields
- values
Security_Entity_Analytics_API_WatchlistEntityUnassignResponseItem:
example:
euid: user:john.doe
status: success
type: object
properties:
error:
description: Error message if the entity failed to process
example: Invalid entity type
type: string
euid:
description: The EUID of the entity
example: user:john.doe
type: string
status:
enum:
- success
- failure
- not_found
example: success
type: string
required:
- euid
- status
Security_Entity_Analytics_API_PrivmonUserCsvUploadStats:
type: object
properties:
failedOperations:
type: integer
successfulOperations:
type: integer
totalOperations:
type: integer
uploaded:
type: integer
required:
- successfulOperations
- uploaded
- failedOperations
- totalOperations
Security_Entity_Analytics_API_EntityRiskScoreRecord:
type: object
properties:
'@timestamp':
description: The time at which the risk score was calculated.
example: '2017-07-21T17:32:28Z'
format: date-time
type: string
calculated_level:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskLevels'
description: Lexical description of the entity's risk.
example: Critical
calculated_score:
description: The raw numeric value of the given entity's risk score.
format: double
type: number
calculated_score_norm:
description: The normalized numeric value of the given entity's risk score. Useful for comparing with other entities.
format: double
maximum: 100
minimum: 0
type: number
calculation_run_id:
description: Unique identifier for the scoring run that produced this document.
type: string
category_1_count:
description: The number of risk input documents that contributed to the Category 1 score (`category_1_score`).
type: integer
category_1_score:
description: The contribution of Category 1 to the overall risk score (`calculated_score`). Category 1 contains Detection Engine Alerts.
format: double
type: number
category_2_count:
type: integer
category_2_score:
format: double
type: number
criticality_level:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
criticality_modifier:
format: double
type: number
id_field:
description: The identifier field defining this risk score. Coupled with `id_value`, uniquely identifies the entity being scored.
example: host.name
type: string
id_value:
description: The identifier value defining this risk score. Coupled with `id_field`, uniquely identifies the entity being scored.
example: example.host
type: string
inputs:
description: A list of the highest-risk documents contributing to this risk score. Useful for investigative purposes.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_RiskScoreInput'
type: array
modifiers:
description: A list of modifiers that were applied to the risk score calculation.
items:
type: object
properties:
contribution:
format: double
type: number
metadata:
additionalProperties: true
type: object
modifier_value:
format: double
type: number
subtype:
type: string
type:
type: string
required:
- type
- contribution
type: array
notes:
items:
type: string
type: array
related_entities:
items:
type: object
properties:
entity_id:
type: string
relationship_type:
type: string
type: array
score_type:
description: Distinguishes base, propagated, and resolution scores.
enum:
- base
- propagated
- resolution
type: string
required:
- '@timestamp'
- id_field
- id_value
- calculated_level
- calculated_score
- calculated_score_norm
- category_1_score
- category_1_count
- inputs
- notes
Security_Entity_Analytics_API_IndexPattern:
description: An additional Elasticsearch index pattern to include as a source for entity data. Merged with the default data view indices when the engine runs.
example: logs-*
type: string
Security_Entity_Analytics_API_MonitoringEngineDescriptor:
type: object
properties:
error:
type: object
properties:
message:
description: Error message typically only present if the engine is in error state
type: string
status:
$ref: '#/components/schemas/Security_Entity_Analytics_API_PrivilegeMonitoringEngineStatus'
required:
- status
Security_Entity_Analytics_API_UserName:
type: object
properties:
entity_analytics_monitoring:
description: Entity analytics monitoring configuration for the user
type: object
properties:
labels:
description: Array of labels associated with the user
items:
type: object
properties:
field:
description: The field name for the label
type: string
source:
description: The source where this label was created (api, csv, or index_sync)
enum:
- api
- csv
- index_sync
type: string
value:
description: The value of the label
type: string
type: array
user:
type: object
properties:
name:
description: The name of the user.
type: string
Security_Entity_Analytics_API_WatchlistCsvUploadResponseItem:
example:
matchedEntities: 1
status: success
type: object
properties:
error:
description: Error message if the row failed to process
example: Invalid entity type
type: string
matchedEntities:
description: Number of entities matched for this row
example: 1
type: integer
status:
enum:
- success
- failure
- unmatched
example: success
type: string
required:
- status
- matchedEntities
Security_Entity_Analytics_API_MonitoringEntitySource:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoringEntitySourceProperties'
- type: object
properties:
id:
type: string
required:
- type
- name
- id
- managed
Security_Entity_Analytics_API_MonitoredUserDoc:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoredUserUpdateDoc'
- type: object
properties:
'@timestamp':
format: date-time
type: string
event:
type: object
properties:
'@timestamp':
format: date-time
type: string
ingested:
format: date-time
type: string
user:
type: object
properties:
entity:
type: object
properties:
attributes:
type: object
properties:
Privileged:
description: Indicates if the user is privileged.
type: boolean
is_privileged:
description: Indicates if the user is privileged.
type: boolean
name:
type: string
Security_Entity_Analytics_API_MonitoredUserUpdateDoc:
type: object
properties:
entity_analytics_monitoring:
type: object
properties:
labels:
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_MonitoringLabel'
type: array
id:
type: string
labels:
type: object
properties:
source_ids:
items:
type: string
type: array
source_integrations:
items:
type: string
type: array
sources:
items:
enum:
- csv
- index_sync
- api
type: array
user:
type: object
properties:
is_privileged:
description: Indicates if the user is privileged.
type: boolean
name:
type: string
securitySchemes:
apiKeyAuth:
description: 'These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`
'
in: header
name: Authorization
type: apiKey
basicAuth:
scheme: basic
type: http
x-topics:
- title: Kibana spaces
content: "Spaces enable you to organize your dashboards and other saved objects into meaningful categories.\nYou can use the default space or create your own spaces.\n\nTo run APIs in non-default spaces, you must add `s/{space_id}/` to the path.\nFor example:\n\n```bash\ncurl -X GET \"http://${KIBANA_URL}/s/marketing/api/data_views\" \\\n -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nIf you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.\n\nTo learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).\n"