def put_watch(
        self,
        *,
        id: str,
        actions: t.Optional[t.Mapping[str, t.Mapping[str, t.Any]]] = None,
        active: t.Optional[bool] = None,
        condition: t.Optional[t.Mapping[str, t.Any]] = None,
        error_trace: t.Optional[bool] = None,
        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
        human: t.Optional[bool] = None,
        if_primary_term: t.Optional[int] = None,
        if_seq_no: t.Optional[int] = None,
        input: t.Optional[t.Mapping[str, t.Any]] = None,
        metadata: t.Optional[t.Mapping[str, t.Any]] = None,
        pretty: t.Optional[bool] = None,
        throttle_period: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
        throttle_period_in_millis: t.Optional[t.Any] = None,
        transform: t.Optional[t.Mapping[str, t.Any]] = None,
        trigger: t.Optional[t.Mapping[str, t.Any]] = None,
        version: t.Optional[int] = None,
        body: t.Optional[t.Dict[str, t.Any]] = None,
    ) -> ObjectApiResponse[t.Any]:
        """
        .. raw:: html

          <p>Create or update a watch.
          When a watch is registered, a new document that represents the watch is added to the <code>.watches</code> index and its trigger is immediately registered with the relevant trigger engine.
          Typically for the <code>schedule</code> trigger, the scheduler is the trigger engine.</p>
          <p>IMPORTANT: You must use Kibana or this API to create a watch.
          Do not add a watch directly to the <code>.watches</code> index by using the Elasticsearch index API.
          If Elasticsearch security features are enabled, do not give users write privileges on the <code>.watches</code> index.</p>
          <p>When you add a watch you can also define its initial active state by setting the <em>active</em> parameter.</p>
          <p>When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.
          If the user is able to read index <code>a</code>, but not index <code>b</code>, the same will apply when the watch runs.</p>


        `<https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-put-watch>`_

        :param id: The identifier for the watch.
        :param actions: The list of actions that will be run if the condition matches.
        :param active: The initial state of the watch. The default value is `true`, which
            means the watch is active by default.
        :param condition: The condition that defines if the actions should be run.
        :param if_primary_term: only update the watch if the last operation that has
            changed the watch has the specified primary term
        :param if_seq_no: only update the watch if the last operation that has changed
            the watch has the specified sequence number
        :param input: The input that defines the input that loads the data for the watch.
        :param metadata: Metadata JSON that will be copied into the history entries.
        :param throttle_period: The minimum time between actions being run. The default
            is 5 seconds. This default can be changed in the config file with the setting
            `xpack.watcher.throttle.period.default_period`. If both this value and the
            `throttle_period_in_millis` parameter are specified, Watcher uses the last
            parameter included in the request.
        :param throttle_period_in_millis: Minimum time in milliseconds between actions
            being run. Defaults to 5000. If both this value and the throttle_period parameter
            are specified, Watcher uses the last parameter included in the request.
        :param transform: The transform that processes the watch payload to prepare it
            for the watch actions.
        :param trigger: The trigger that defines when the watch should run.
        :param version: Explicit version number for concurrency control
        """
        if id in SKIP_IN_PATH:
            raise ValueError("Empty value passed for parameter 'id'")
        __path_parts: t.Dict[str, str] = {"id": _quote(id)}
        __path = f'/_watcher/watch/{__path_parts["id"]}'
        __query: t.Dict[str, t.Any] = {}
        __body: t.Dict[str, t.Any] = body if body is not None else {}
        if active is not None:
            __query["active"] = active
        if error_trace is not None:
            __query["error_trace"] = error_trace
        if filter_path is not None:
            __query["filter_path"] = filter_path
        if human is not None:
            __query["human"] = human
        if if_primary_term is not None:
            __query["if_primary_term"] = if_primary_term
        if if_seq_no is not None:
            __query["if_seq_no"] = if_seq_no
        if pretty is not None:
            __query["pretty"] = pretty
        if version is not None:
            __query["version"] = version
        if not __body:
            if actions is not None:
                __body["actions"] = actions
            if condition is not None:
                __body["condition"] = condition
            if input is not None:
                __body["input"] = input
            if metadata is not None:
                __body["metadata"] = metadata
            if throttle_period is not None:
                __body["throttle_period"] = throttle_period
            if throttle_period_in_millis is not None:
                __body["throttle_period_in_millis"] = throttle_period_in_millis
            if transform is not None:
                __body["transform"] = transform
            if trigger is not None:
                __body["trigger"] = trigger
        if not __body:
            __body = None  # type: ignore[assignment]
        __headers = {"accept": "application/json"}
        if __body is not None:
            __headers["content-type"] = "application/json"
        return self.perform_request(  # type: ignore[return-value]
            "PUT",
            __path,
            params=__query,
            headers=__headers,
            body=__body,
            endpoint_id="watcher.put_watch",
            path_parts=__path_parts,
        )

        .. raw:: html

          <p>Create or update a watch.
          When a watch is registered, a new document that represents the watch is added to the <code>.watches</code> index and its trigger is immediately registered with the relevant trigger engine.
          Typically for the <code>schedule</code> trigger, the scheduler is the trigger engine.</p>
          <p>IMPORTANT: You must use Kibana or this API to create a watch.
          Do not add a watch directly to the <code>.watches</code> index by using the Elasticsearch index API.
          If Elasticsearch security features are enabled, do not give users write privileges on the <code>.watches</code> index.</p>
          <p>When you add a watch you can also define its initial active state by setting the <em>active</em> parameter.</p>
          <p>When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges.
          If the user is able to read index <code>a</code>, but not index <code>b</code>, the same will apply when the watch runs.</p>


        `<https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-put-watch>`_

        :param id: The identifier for the watch.
        :param actions: The list of actions that will be run if the condition matches.
        :param active: The initial state of the watch. The default value is `true`, which
            means the watch is active by default.
        :param condition: The condition that defines if the actions should be run.
        :param if_primary_term: only update the watch if the last operation that has
            changed the watch has the specified primary term
        :param if_seq_no: only update the watch if the last operation that has changed
            the watch has the specified sequence number
        :param input: The input that defines the input that loads the data for the watch.
        :param metadata: Metadata JSON that will be copied into the history entries.
        :param throttle_period: The minimum time between actions being run. The default
            is 5 seconds. This default can be changed in the config file with the setting
            `xpack.watcher.throttle.period.default_period`. If both this value and the
            `throttle_period_in_millis` parameter are specified, Watcher uses the last
            parameter included in the request.
        :param throttle_period_in_millis: Minimum time in milliseconds between actions
            being run. Defaults to 5000. If both this value and the throttle_period parameter
            are specified, Watcher uses the last parameter included in the request.
        :param transform: The transform that processes the watch payload to prepare it
            for the watch actions.
        :param trigger: The trigger that defines when the watch should run.
        :param version: Explicit version number for concurrency control
        
elasticsearch/_sync/client/watcher.py