Microsoft Sentinel Watchlists API

openapi: 3.2.0
info:
  title: Microsoft Sentinel Watchlists API
  version: '2025-09-01'
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
  description: 'Operations tagged Watchlists across 2 of this provider''s published API definitions: microsoft-sentinel-securityinsights-2025-09-01.json, microsoft-sentinel-securityinsights-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: Watchlists
paths:
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/watchlists
  : get:
      operationId: Watchlists_List
      tags:
      - Watchlists
      description: Get all watchlists, without watchlist items.
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: workspaceName
        in: path
        description: The name of the monitor workspace.
        required: true
        schema:
          type: string
          maxLength: 90
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
      - name: $skipToken
        in: query
        description: Skiptoken is only used if a previous operation returned a partial result. If a previous response contains a nextLink element, the value of the nextLink element will include a skiptoken parameter that specifies a starting point to use for subsequent calls. Optional.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WatchlistList'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      x-ms-examples:
        Get all watchlists.:
          $ref: ./examples/watchlists/GetWatchlists.json
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Watchlists list
      x-summary-source: derived
    servers:
    - url: https://management.azure.com
  ? /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/watchlists/{watchlistAlias}
  : get:
      operationId: Watchlists_Get
      tags:
      - Watchlists
      description: Get a watchlist, without its watchlist items.
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: workspaceName
        in: path
        description: The name of the monitor workspace.
        required: true
        schema:
          type: string
          maxLength: 90
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
      - name: watchlistAlias
        in: path
        description: The watchlist alias
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CloudError'
      x-ms-examples:
        Get a watchlist.:
          $ref: ./examples/watchlists/GetWatchlistByAlias.json
      summary: Watchlists get
      x-summary-source: derived
    put:
      operationId: Watchlists_CreateOrUpdate
      tags:
      - Watchlists
      description: 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.
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: workspaceName
        in: path
        description: The name of the monitor workspace.
        required: true
        schema:
          type: string
          maxLength: 90
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
      - name: watchlistAlias
        in: path
        description: The watchlist alias
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Resource 'Watchlist' update operation succeeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        '201':
          description: Resource 'Watchlist' create operation succeeded
          headers:
            Azure-AsyncOperation:
              description: A link to the status monitor
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Watchlist'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: ../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        Create or update a watchlist and bulk creates watchlist items.:
          $ref: ./examples/watchlists/CreateWatchlistAndWatchlistItems.json
        Create or update a watchlist.:
          $ref: ./examples/watchlists/CreateWatchlist.json
      x-ms-long-running-operation-options:
        final-state-via: azure-async-operation
        final-state-schema: '#/definitions/Watchlist'
      x-ms-long-running-operation: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Watchlist'
        description: The watchlist
        required: true
      summary: Watchlists create or update
      x-summary-source: derived
    delete:
      operationId: Watchlists_Delete
      tags:
      - Watchlists
      description: Delete a watchlist.
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/SubscriptionIdParameter
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/parameters/ResourceGroupNameParameter
      - name: workspaceName
        in: path
        description: The name of the monitor workspace.
        required: true
        schema:
          type: string
          maxLength: 90
          minLength: 1
          pattern: ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$
      - name: watchlistAlias
        in: path
        description: The watchlist alias
        required: true
        schema:
          type: string
      responses:
        '202':
          description: Resource deletion accepted.
          headers:
            Azure-AsyncOperation:
              description: A link to the status monitor
              schema:
                type: string
                format: uri
            Location:
              description: The Location header contains the URL where the status of the long running operation can be checked.
              schema:
                type: string
        '204':
          description: Resource does not exist.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: ../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse
      x-ms-examples:
        Delete a watchlist.:
          $ref: ./examples/watchlists/DeleteWatchlist.json
      x-ms-long-running-operation-options:
        final-state-via: azure-async-operation
        final-state-schema: '#/definitions/Watchlist'
      x-ms-long-running-operation: true
      summary: Watchlists delete
      x-summary-source: derived
    servers:
    - url: https://management.azure.com
components:
  schemas:
    WatchlistProperties:
      type: object
      description: Describes watchlist properties
      properties:
        watchlistId:
          type: string
          description: The id (a Guid) of the watchlist
        displayName:
          type: string
          description: The display name of the watchlist
        provider:
          type: string
          description: The provider of the watchlist
        source:
          type: string
          description: The filename of the watchlist, called 'source'
        sourceType:
          $ref: '#/components/schemas/SourceType'
          description: The sourceType of the watchlist
        created:
          type: string
          format: date-time
          description: The time the watchlist was created
        updated:
          type: string
          format: date-time
          description: The last time the watchlist was updated
        createdBy:
          $ref: '#/components/schemas/UserInfo'
          description: Describes a user that created the watchlist
        updatedBy:
          $ref: '#/components/schemas/UserInfo'
          description: Describes a user that updated the watchlist
        description:
          type: string
          description: A description of the watchlist
        watchlistType:
          type: string
          description: The type of the watchlist
        watchlistAlias:
          type: string
          description: The alias of the watchlist
        isDeleted:
          type: boolean
          description: A flag that indicates if the watchlist is deleted or not
        labels:
          type: array
          description: List of labels relevant to this watchlist
          items:
            type: string
        defaultDuration:
          type: string
          format: duration
          description: The default duration of a watchlist (in ISO 8601 duration format)
        tenantId:
          type: string
          description: The tenantId where the watchlist belongs to
        numberOfLinesToSkip:
          type: integer
          format: int32
          description: The number of lines in a csv/tsv content to skip before the header
        rawContent:
          type: string
          description: 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
        itemsSearchKey:
          type: string
          description: 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.
        contentType:
          type: string
          description: 'The content type of the raw content. Example : text/csv or text/tsv'
        uploadStatus:
          type: string
          description: 'The status of the Watchlist upload : New, InProgress or Complete. **Note** : When a Watchlist upload status is InProgress, the Watchlist cannot be deleted'
        provisioningState:
          $ref: '#/components/schemas/WatchlistProvisioningState'
          description: Describes provisioning state
          readOnly: true
      required:
      - displayName
      - provider
      - itemsSearchKey
    WatchlistList:
      type: object
      description: List all the watchlists.
      properties:
        value:
          type: array
          description: The Watchlist items on this page
          items:
            $ref: '#/components/schemas/Watchlist'
        nextLink:
          type: string
          format: uri
          description: The link to the next page of items
          readOnly: true
      required:
      - value
    UserInfo:
      type: object
      description: User information that made some action
      properties:
        email:
          type: string
          description: The email of the user.
          readOnly: true
        name:
          type: string
          description: The name of the user.
          readOnly: true
        objectId:
          $ref: '#/components/schemas/Azure.Core.uuid'
          description: The object id of the user.
    SourceType:
      type: string
      description: The sourceType of the watchlist
      enum:
      - Local
      - AzureStorage
      x-ms-enum:
        name: SourceType
        modelAsString: true
        values:
        - name: Local
          value: Local
          description: The source from local file.
        - name: AzureStorage
          value: AzureStorage
          description: The source from Azure storage.
    CloudErrorBody:
      type: object
      description: Error details.
      properties:
        code:
          type: string
          description: An identifier for the error. Codes are invariant and are intended to be consumed programmatically.
          readOnly: true
        message:
          type: string
          description: A message describing the error, intended to be suitable for display in a user interface.
          readOnly: true
    Watchlist:
      type: object
      description: Represents a Watchlist in Azure Security Insights.
      properties:
        properties:
          $ref: '#/components/schemas/WatchlistProperties'
          description: Watchlist properties
          x-ms-client-flatten: true
        etag:
          type: string
          description: Etag of the azure resource
      allOf:
      - $ref: ../../../../../../common-types/resource-management/v5/types.json#/definitions/ProxyResource
    WatchlistProvisioningState:
      type: string
      description: The provisioning state of the watchlist
      enum:
      - New
      - InProgress
      - Uploading
      - Deleting
      - Succeeded
      - Failed
      - Canceled
      x-ms-enum:
        name: WatchlistProvisioningState
        modelAsString: true
        values:
        - name: New
          value: New
          description: New
        - name: InProgress
          value: InProgress
          description: InProgress
        - name: Uploading
          value: Uploading
          description: Uploading
        - name: Deleting
          value: Deleting
          description: Deleting
        - name: Succeeded
          value: Succeeded
          description: Succeeded
        - name: Failed
          value: Failed
          description: Failed
        - name: Canceled
          value: Canceled
          description: Canceled
    CloudError:
      type: object
      description: Error response structure.
      properties:
        error:
          $ref: '#/components/schemas/CloudErrorBody'
          description: Error data
    Azure.Core.uuid:
      type: string
      format: uuid
      description: Universally Unique Identifier
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow.
x-refined-from:
- microsoft-sentinel-securityinsights-2025-09-01.json
- microsoft-sentinel-securityinsights-openapi.yml