Watchlists - Create Or Update

Reference

Service:: Sentinel

API Version:: 2025-03-01

Create or update a Watchlist and its Watchlist Items (bulk creation, e.g. through text/csv content type). To create a Watchlist and its Items, we should call this endpoint with rawContent and contentType properties.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/watchlists/{watchlistAlias}?api-version=2025-03-01

URI Parameters

Name	In	Required	Type	Description
resourceGroupName	path	True	string minLength: 1 maxLength: 90	The name of the resource group. The name is case insensitive.
subscriptionId	path	True	string (uuid)	The ID of the target subscription. The value must be an UUID.
watchlistAlias	path	True	string	The watchlist alias
workspaceName	path	True	string minLength: 1 maxLength: 90 pattern: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$	The name of the workspace.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Required	Type	Description
properties.displayName	True	string	The display name of the watchlist
properties.itemsSearchKey	True	string	The search key is used to optimize query performance when using watchlists for joins with other data. For example, enable a column with IP addresses to be the designated SearchKey field, then use this field as the key field when joining to other event data by IP address.
properties.provider	True	string	The provider of the watchlist
etag		string	Etag of the azure resource
properties.contentType		string	The content type of the raw content. Example : text/csv or text/tsv
properties.created		string (date-time)	The time the watchlist was created
properties.createdBy		UserInfo	Describes a user that created the watchlist
properties.defaultDuration		string (duration)	The default duration of a watchlist (in ISO 8601 duration format)
properties.description		string	A description of the watchlist
properties.isDeleted		boolean	A flag that indicates if the watchlist is deleted or not
properties.labels		string[]	List of labels relevant to this watchlist
properties.numberOfLinesToSkip		integer (int32)	The number of lines in a csv/tsv content to skip before the header
properties.rawContent		string	The raw content that represents to watchlist items to create. In case of csv/tsv content type, it's the content of the file that will parsed by the endpoint
properties.source		string	The filename of the watchlist, called 'source'
properties.sourceType		sourceType	The sourceType of the watchlist
properties.tenantId		string	The tenantId where the watchlist belongs to
properties.updated		string (date-time)	The last time the watchlist was updated
properties.updatedBy		UserInfo	Describes a user that updated the watchlist
properties.uploadStatus		string	The status of the Watchlist upload : New, InProgress or Complete. Note : When a Watchlist upload status is InProgress, the Watchlist cannot be deleted
properties.watchlistAlias		string	The alias of the watchlist
properties.watchlistId		string	The id (a Guid) of the watchlist
properties.watchlistType		string	The type of the watchlist

Responses

Name	Type	Description
200 OK	Watchlist	OK
201 Created	Watchlist	Created. The response includes the Provisioning State and the Azure-AsyncOperation header. To get the progress of the operation, call GET operation on the URL in Azure-AsyncOperation header field. Headers Azure-AsyncOperation: string
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Name

Type

Description

200 OK

Watchlist

201 Created

Watchlist

Created. The response includes the Provisioning State and the Azure-AsyncOperation header. To get the progress of the operation, call GET operation on the URL in Azure-AsyncOperation header field.

Headers

Azure-AsyncOperation: string

Other Status Codes

ErrorResponse

Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

Create or update a watchlist and bulk creates watchlist items.

Create or update a watchlist.

Create or update a watchlist and bulk creates watchlist items.

Sample request

HTTP

PUT https://management.azure.com/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/watchlists/highValueAsset?api-version=2025-03-01

{
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "properties": {
    "displayName": "High Value Assets Watchlist",
    "source": "watchlist.csv",
    "sourceType": "Local",
    "provider": "Microsoft",
    "description": "Watchlist from CSV content",
    "numberOfLinesToSkip": 1,
    "rawContent": "This line will be skipped\nheader1,header2\nvalue1,value2",
    "itemsSearchKey": "header1",
    "contentType": "text/csv"
  }
}

Sample response

Status code:: 200

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalIinsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/watchlists/highValueAsset",
  "name": "highValueAsset",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "type": "Microsoft.SecurityInsights/Watchlists",
  "properties": {
    "watchlistId": "76d5a51f-ba1f-4038-9d22-59fda38dc017",
    "displayName": "High Value Assets Watchlist",
    "provider": "Microsoft",
    "source": "watchlist.csv",
    "sourceType": "Local",
    "created": "2020-09-28T00:26:54.7746089+00:00",
    "updated": "2020-09-28T00:26:57+00:00",
    "createdBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "updatedBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "description": "Watchlist from CSV content",
    "watchlistType": "watchlist",
    "watchlistAlias": "highValueAsset",
    "itemsSearchKey": "header1",
    "isDeleted": false,
    "tenantId": "f686d426-8d16-42db-81b7-ab578e110ccd"
  }
}

Status code:: 201

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalIinsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/watchlists/highValueAsset",
  "name": "highValueAsset",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "type": "Microsoft.SecurityInsights/Watchlists",
  "properties": {
    "watchlistId": "76d5a51f-ba1f-4038-9d22-59fda38dc017",
    "displayName": "High Value Assets Watchlist",
    "provider": "Microsoft",
    "source": "watchlist.csv",
    "sourceType": "Local",
    "created": "2020-09-28T00:26:54.7746089+00:00",
    "updated": "2020-09-28T00:26:57+00:00",
    "createdBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "updatedBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "description": "Watchlist from CSV content",
    "watchlistType": "watchlist",
    "watchlistAlias": "highValueAsset",
    "itemsSearchKey": "header1",
    "isDeleted": false,
    "tenantId": "f686d426-8d16-42db-81b7-ab578e110ccd"
  }
}

Create or update a watchlist.

Sample request

HTTP

PUT https://management.azure.com/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalInsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/watchlists/highValueAsset?api-version=2025-03-01

{
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "properties": {
    "displayName": "High Value Assets Watchlist",
    "source": "watchlist.csv",
    "sourceType": "Local",
    "provider": "Microsoft",
    "description": "Watchlist from CSV content",
    "itemsSearchKey": "header1"
  }
}

Sample response

Status code:: 200

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalIinsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/watchlists/highValueAsset",
  "name": "highValueAsset",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "type": "Microsoft.SecurityInsights/Watchlists",
  "properties": {
    "watchlistId": "76d5a51f-ba1f-4038-9d22-59fda38dc017",
    "displayName": "High Value Assets Watchlist",
    "provider": "Microsoft",
    "source": "watchlist.csv",
    "sourceType": "Local",
    "created": "2020-09-28T00:26:54.7746089+00:00",
    "updated": "2020-09-28T00:26:57+00:00",
    "createdBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "updatedBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "description": "Watchlist from CSV content",
    "watchlistType": "watchlist",
    "watchlistAlias": "highValueAsset",
    "itemsSearchKey": "header1",
    "isDeleted": false,
    "tenantId": "f686d426-8d16-42db-81b7-ab578e110ccd"
  }
}

Status code:: 201

{
  "id": "/subscriptions/d0cfe6b2-9ac0-4464-9919-dccaee2e48c0/resourceGroups/myRg/providers/Microsoft.OperationalIinsights/workspaces/myWorkspace/providers/Microsoft.SecurityInsights/watchlists/highValueAsset",
  "name": "highValueAsset",
  "etag": "\"0300bf09-0000-0000-0000-5c37296e0000\"",
  "type": "Microsoft.SecurityInsights/Watchlists",
  "properties": {
    "watchlistId": "76d5a51f-ba1f-4038-9d22-59fda38dc017",
    "displayName": "High Value Assets Watchlist",
    "provider": "Microsoft",
    "source": "watchlist.csv",
    "sourceType": "Local",
    "created": "2020-09-28T00:26:54.7746089+00:00",
    "updated": "2020-09-28T00:26:57+00:00",
    "createdBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "updatedBy": {
      "objectId": "2046feea-040d-4a46-9e2b-91c2941bfa70",
      "email": "john@contoso.com",
      "name": "john doe"
    },
    "description": "Watchlist from CSV content",
    "watchlistType": "watchlist",
    "watchlistAlias": "highValueAsset",
    "itemsSearchKey": "header1",
    "isDeleted": false,
    "tenantId": "f686d426-8d16-42db-81b7-ab578e110ccd"
  }
}

Definitions

Name	Description
createdByType	The type of identity that created the resource.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
ProvisioningState	Describes provisioning state
sourceType	The sourceType of the watchlist
systemData	Metadata pertaining to creation and last modification of the resource.
UserInfo	User information that made some action
Watchlist	Represents a Watchlist in Azure Security Insights.

createdByType

Enumeration

The type of identity that created the resource.

Value	Description
Application
Key
ManagedIdentity
User

ErrorAdditionalInfo

Object

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

Object

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Object

Error response

Name	Type	Description
error	ErrorDetail	The error object.

ProvisioningState

Enumeration

Describes provisioning state

Value	Description
Canceled	The Canceled provisioning state.
Deleting	The Deleting provisioning state.
Failed	The Failed provisioning state.
InProgress	The InProgress provisioning state.
New	The New provisioning state.
Succeeded	The Succeeded provisioning state.
Uploading	The Uploading provisioning state.

sourceType

Enumeration

The sourceType of the watchlist

Value	Description
AzureStorage	The source from Azure storage.
Local	The source from local file.

systemData

Object

Metadata pertaining to creation and last modification of the resource.

Name	Type	Description
createdAt	string (date-time)	The timestamp of resource creation (UTC).
createdBy	string	The identity that created the resource.
createdByType	createdByType	The type of identity that created the resource.
lastModifiedAt	string (date-time)	The timestamp of resource last modification (UTC)
lastModifiedBy	string	The identity that last modified the resource.
lastModifiedByType	createdByType	The type of identity that last modified the resource.

UserInfo

Object

User information that made some action

Name	Type	Description
email	string	The email of the user.
name	string	The name of the user.
objectId	string (uuid)	The object id of the user.

Watchlist

Object

Represents a Watchlist in Azure Security Insights.

Name	Type	Description
etag	string	Etag of the azure resource
id	string (arm-id)	Fully qualified resource ID for the resource. E.g. "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
name	string	The name of the resource
properties.contentType	string	The content type of the raw content. Example : text/csv or text/tsv
properties.created	string (date-time)	The time the watchlist was created
properties.createdBy	UserInfo	Describes a user that created the watchlist
properties.defaultDuration	string (duration)	The default duration of a watchlist (in ISO 8601 duration format)
properties.description	string	A description of the watchlist
properties.displayName	string	The display name of the watchlist
properties.isDeleted	boolean	A flag that indicates if the watchlist is deleted or not
properties.itemsSearchKey	string	The search key is used to optimize query performance when using watchlists for joins with other data. For example, enable a column with IP addresses to be the designated SearchKey field, then use this field as the key field when joining to other event data by IP address.
properties.labels	string[]	List of labels relevant to this watchlist
properties.numberOfLinesToSkip	integer (int32)	The number of lines in a csv/tsv content to skip before the header
properties.provider	string	The provider of the watchlist
properties.provisioningState	ProvisioningState	Describes provisioning state
properties.rawContent	string	The raw content that represents to watchlist items to create. In case of csv/tsv content type, it's the content of the file that will parsed by the endpoint
properties.source	string	The filename of the watchlist, called 'source'
properties.sourceType	sourceType	The sourceType of the watchlist
properties.tenantId	string	The tenantId where the watchlist belongs to
properties.updated	string (date-time)	The last time the watchlist was updated
properties.updatedBy	UserInfo	Describes a user that updated the watchlist
properties.uploadStatus	string	The status of the Watchlist upload : New, InProgress or Complete. Note : When a Watchlist upload status is InProgress, the Watchlist cannot be deleted
properties.watchlistAlias	string	The alias of the watchlist
properties.watchlistId	string	The id (a Guid) of the watchlist
properties.watchlistType	string	The type of the watchlist
systemData	systemData	Azure Resource Manager metadata containing createdBy and modifiedBy information.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

Share via

Watchlists - Create Or Update

URI Parameters

Request Body

Responses

Security

azure_auth

Scopes

Examples

Create or update a watchlist and bulk creates watchlist items.

Sample request

Sample response

Create or update a watchlist.

Sample request

Sample response

Definitions

createdByType

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

ProvisioningState

sourceType

systemData

UserInfo

Watchlist

Additional resources