PUT /api/fleet/agent_policies/{agentPolicyId}
Api key auth Basic auth

Spaces method and path for this operation:

put /s/{space_id}/api/fleet/agent_policies/{agentPolicyId}

Refer to Spaces for more information.

Update an agent policy by ID.

[Required authorization] Route required privileges: fleet-agent-policies-all.

Headers

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Path parameters

  • agentPolicyId string Required

Query parameters

  • format string

    Values are simplified or legacy.

application/json

Body

  • advanced_settings object

    Additional properties are NOT allowed.

    Hide advanced_settings attributes Show advanced_settings attributes object
    • agent_download_target_directory
    • agent_download_timeout
    • agent_features_disable_policy_change_acks_enabled
    • agent_internal
    • agent_limits_go_max_procs
    • agent_logging_files_interval
    • agent_logging_files_keepfiles
    • agent_logging_files_rotateeverybytes
    • agent_logging_level
    • agent_logging_metrics_period
    • agent_logging_to_files
    • agent_monitoring_runtime_experimental
  • agent_features array[object]

    Not more than 100 elements.

    Hide agent_features attributes Show agent_features attributes object
    • enabled boolean Required
    • name string Required
  • agentless object

    Additional properties are NOT allowed.

    Hide agentless attributes Show agentless attributes object
    • cloud_connectors object

      Additional properties are NOT allowed.

      Hide cloud_connectors attributes Show cloud_connectors attributes object
      • enabled boolean Required
      • target_csp string

        Values are aws, azure, or gcp.

    • resources object

      Additional properties are NOT allowed.

      Hide resources attribute Show resources attribute object
      • requests object

        Additional properties are NOT allowed.

        Hide requests attributes Show requests attributes object
        • cpu string
        • memory string
  • bumpRevision boolean
  • data_output_id string | null
  • description string
  • download_source_id string | null
  • fleet_server_host_id string | null
  • force boolean
  • global_data_tags array[object]

    User defined data tags that are added to all of the inputs. The values can be strings or numbers.

    Not more than 100 elements.

    Hide global_data_tags attributes Show global_data_tags attributes object
  • has_agent_version_conditions boolean
  • has_fleet_server boolean
  • id string
  • inactivity_timeout number

    Minimum value is 0. Default value is 1209600.

  • is_default boolean
  • is_default_fleet_server boolean
  • is_managed boolean
  • is_protected boolean
  • is_verifier boolean

    Indicates this is a short-lived verifier policy used for OTel permission verification.

  • keep_monitoring_alive boolean | null

    When set to true, monitoring will be enabled but logs/metrics collection will be disabled

    Default value is false.

  • monitoring_diagnostics object

    Additional properties are NOT allowed.

    Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
    • limit object

      Additional properties are NOT allowed.

      Hide limit attributes Show limit attributes object
      • burst number
      • interval string
    • uploader object

      Additional properties are NOT allowed.

      Hide uploader attributes Show uploader attributes object
      • init_dur string
      • max_dur string
      • max_retries number
  • monitoring_enabled array[string]

    Not more than 3 elements. Values are logs, metrics, or traces.

  • monitoring_http object

    Additional properties are NOT allowed.

    Hide monitoring_http attributes Show monitoring_http attributes object
    • buffer object

      Additional properties are NOT allowed.

      Hide buffer attribute Show buffer attribute object
      • enabled boolean

        Default value is false.

    • enabled boolean
    • host string
    • port number

      Minimum value is 0, maximum value is 65353.

  • monitoring_output_id string | null
  • monitoring_pprof_enabled boolean
  • name string Required

    Minimum length is 1.

  • namespace string Required

    Minimum length is 1.

  • overrides object | null

    Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.

  • required_versions array[object] | null

    Not more than 100 elements.

    Hide required_versions attributes Show required_versions attributes object
    • percentage number Required

      Target percentage of agents to auto upgrade

      Minimum value is 0, maximum value is 100.

    • version string Required

      Target version for automatic agent upgrade

  • space_ids array[string]

    Not more than 100 elements.

  • supports_agentless boolean | null Deprecated

    Indicates whether the agent policy supports agentless integrations. Deprecated in favor of the Fleet agentless policies API.

    Default value is false.

  • unenroll_timeout number

    Minimum value is 0.

Responses

  • 200 application/json

    Successful response

    Hide response attribute Show response attribute object
    • item object Required

      Additional properties are NOT allowed.

      Hide item attributes Show item attributes object
      • advanced_settings object

        Additional properties are NOT allowed.

        Hide advanced_settings attributes Show advanced_settings attributes object
        • agent_download_target_directory
        • agent_download_timeout
        • agent_features_disable_policy_change_acks_enabled
        • agent_internal
        • agent_limits_go_max_procs
        • agent_logging_files_interval
        • agent_logging_files_keepfiles
        • agent_logging_files_rotateeverybytes
        • agent_logging_level
        • agent_logging_metrics_period
        • agent_logging_to_files
        • agent_monitoring_runtime_experimental
      • agent_features array[object]

        Not more than 100 elements.

        Hide agent_features attributes Show agent_features attributes object
        • enabled boolean Required
        • name string Required
      • agentless object

        Additional properties are NOT allowed.

        Hide agentless attributes Show agentless attributes object
        • cloud_connectors object

          Additional properties are NOT allowed.

          Hide cloud_connectors attributes Show cloud_connectors attributes object
          • enabled boolean Required
          • target_csp string

            Values are aws, azure, or gcp.

        • resources object

          Additional properties are NOT allowed.

          Hide resources attribute Show resources attribute object
          • requests object

            Additional properties are NOT allowed.

            Hide requests attributes Show requests attributes object
            • cpu string
            • memory string
      • agents number
      • agents_per_version array[object]

        Not more than 1000 elements.

        Hide agents_per_version attributes Show agents_per_version attributes object
        • count number Required
        • version string Required
      • created_at string
      • data_output_id string | null
      • description string
      • download_source_id string | null
      • fips_agents number
      • fleet_server_host_id string | null
      • global_data_tags array[object]

        User defined data tags that are added to all of the inputs. The values can be strings or numbers.

        Not more than 100 elements.

        Hide global_data_tags attributes Show global_data_tags attributes object
      • has_agent_version_conditions boolean
      • has_fleet_server boolean
      • id string Required
      • inactivity_timeout number

        Minimum value is 0. Default value is 1209600.

      • is_default boolean
      • is_default_fleet_server boolean
      • is_managed boolean
      • is_preconfigured boolean
      • is_protected boolean Required

        Indicates whether the agent policy has tamper protection enabled. Default false.

      • is_verifier boolean

        Indicates this is a short-lived verifier policy used for OTel permission verification.

      • keep_monitoring_alive boolean | null

        When set to true, monitoring will be enabled but logs/metrics collection will be disabled

        Default value is false.

      • min_agent_version string | null
      • monitoring_diagnostics object

        Additional properties are NOT allowed.

        Hide monitoring_diagnostics attributes Show monitoring_diagnostics attributes object
        • limit object

          Additional properties are NOT allowed.

          Hide limit attributes Show limit attributes object
          • burst number
          • interval string
        • uploader object

          Additional properties are NOT allowed.

          Hide uploader attributes Show uploader attributes object
          • init_dur string
          • max_dur string
          • max_retries number
      • monitoring_enabled array[string]

        Not more than 3 elements. Values are logs, metrics, or traces.

      • monitoring_http object

        Additional properties are NOT allowed.

        Hide monitoring_http attributes Show monitoring_http attributes object
        • buffer object

          Additional properties are NOT allowed.

          Hide buffer attribute Show buffer attribute object
          • enabled boolean

            Default value is false.

        • enabled boolean
        • host string
        • port number

          Minimum value is 0, maximum value is 65353.

      • monitoring_output_id string | null
      • monitoring_pprof_enabled boolean
      • name string Required

        Minimum length is 1.

      • namespace string Required

        Minimum length is 1.

      • overrides object | null

        Override settings that are defined in the agent policy. Input settings cannot be overridden. The override option should be used only in unusual circumstances and not as a routine procedure.

      • package_agent_version_conditions array[object] | null

        Not more than 1000 elements.

        Hide package_agent_version_conditions attributes Show package_agent_version_conditions attributes object
        • name string Required
        • title string Required
        • version_condition string Required

      • package_policies array[string] | array[object]

        Any of:
        array-1 array[string] array-2 array[object]

        Not more than 10000 elements.

        This field is present only when retrieving a single agent policy, or when retrieving a list of agent policies with the ?full=true parameter

        Not more than 10000 elements.

        Hide attributes Show attributes object
        • additional_datastreams_permissions array[string] | null

          Additional datastream permissions, that will be added to the agent policy.

          Not more than 1000 elements.

        • agents number
        • cloud_connector_id string | null

          ID of the cloud connector associated with this package policy.

        • cloud_connector_name string | null

          Transient field for cloud connector name during creation.

          Minimum length is 1, maximum length is 255.

        • created_at string Required
        • created_by string Required
        • description string

          Package policy description

        • elasticsearch object

          Additional properties are allowed.

          Hide elasticsearch attribute Show elasticsearch attribute object
          • privileges object

            Additional properties are allowed.

            Hide privileges attribute Show privileges attribute object
            • cluster array[string]

              Not more than 100 elements.

        • enabled boolean Required
        • id string Required

          Package policy unique identifier.

        • inputs array[object] | object Required

          Package policy inputs.

          Any of:
          array-1 array[object] object-2 object

          Not more than 100 elements.

          Hide attributes Show attributes object
          • compiled_input Required
          • config object

            Package variable (see integration documentation for more information)

            Hide config attribute Show config attribute object
            • * object Additional properties

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
              • frozen boolean
              • type string
              • value Required
          • deprecated object

            Additional properties are NOT allowed.

            Hide deprecated attributes Show deprecated attributes object
            • description string Required
            • replaced_by object
              Hide replaced_by attribute Show replaced_by attribute object
              • * string Additional properties
            • since string
          • enabled boolean Required
          • id string
          • keep_enabled boolean
          • migrate_from string
          • name string
          • policy_template string
          • streams array[object] Required

            Not more than 1000 elements.

            Hide streams attributes Show streams attributes object
            • compiled_stream Required
            • config object

              Package variable (see integration documentation for more information)

              Hide config attribute Show config attribute object
              • * object Additional properties

                Additional properties are NOT allowed.

                Hide * attributes Show * attributes object
                • frozen boolean
                • type string
                • value Required
            • data_stream object Required

              Additional properties are NOT allowed.

              Hide data_stream attributes Show data_stream attributes object
              • dataset string Required
              • elasticsearch object

                Additional properties are NOT allowed.

                Hide elasticsearch attributes Show elasticsearch attributes object
                • dynamic_dataset boolean
                • dynamic_namespace boolean
                • privileges object

                  Additional properties are NOT allowed.

                  Hide privileges attribute Show privileges attribute object
                  • indices array[string]

                    Not more than 100 elements.

              • type string
            • deprecated object

              Additional properties are NOT allowed.

              Hide deprecated attributes Show deprecated attributes object
              • description string Required
              • replaced_by object
                Hide replaced_by attribute Show replaced_by attribute object
                • * string Additional properties
              • since string
            • enabled boolean Required
            • id string
            • keep_enabled boolean
            • migrate_from string
            • release string

              Values are ga, beta, or experimental.

            • var_group_selections object

              Variable group selections. Maps var_group name to the selected option name within that group.

              Hide var_group_selections attribute Show var_group_selections attribute object
              • * string Additional properties
            • vars object

              Package variable (see integration documentation for more information)

              Hide vars attribute Show vars attribute object
              • * object Additional properties

                Additional properties are NOT allowed.

                Hide * attributes Show * attributes object
                • frozen boolean
                • type string
                • value Required
          • type string Required
          • var_group_selections object

            Variable group selections. Maps var_group name to the selected option name within that group.

            Hide var_group_selections attribute Show var_group_selections attribute object
            • * string Additional properties
          • vars object

            Package variable (see integration documentation for more information)

            Hide vars attribute Show vars attribute object
            • * object Additional properties

              Additional properties are NOT allowed.

              Hide * attributes Show * attributes object
              • frozen boolean
              • type string
              • value Required
        • is_managed boolean
        • name string Required

          Unique name for the package policy.

        • namespace string

          The package policy namespace. Leave blank to inherit the agent policy's namespace.

        • output_id string | null
        • overrides object | null

          Override settings that are defined in the package policy. The override option should be used only in unusual circumstances and not as a routine procedure.

          Additional properties are NOT allowed.

          Hide overrides attribute Show overrides attribute object | null
          • inputs object
        • package object

          Additional properties are NOT allowed.

          Hide package attributes Show package attributes object
          • experimental_data_stream_features array[object]

            Not more than 100 elements.

            Hide experimental_data_stream_features attributes Show experimental_data_stream_features attributes object
            • data_stream string Required
            • features object Required

              Additional properties are NOT allowed.

              Hide features attributes Show features attributes object
              • doc_value_only_numeric boolean
              • doc_value_only_other boolean
              • synthetic_source boolean
              • tsdb boolean
          • fips_compatible boolean
          • name string Required

            Package name

          • requires_root boolean
          • title string
          • version string Required

            Package version

        • package_agent_version_condition string
        • policy_id string | null Deprecated

          ID of the agent policy which the package policy will be added to.

        • policy_ids array[string]

          IDs of the agent policies which that package policy will be added to.

          Not more than 1000 elements.

        • revision number Required

          Package policy revision.

        • secret_references array[object]

          Not more than 1000 elements.

          Hide secret_references attribute Show secret_references attribute object
          • id string Required
        • spaceIds array[string]

          Not more than 100 elements.

        • supports_agentless boolean | null

          Indicates whether the package policy belongs to an agentless agent policy.

          Default value is false.

        • supports_cloud_connector boolean | null

          Indicates whether the package policy supports cloud connectors.

          Default value is false.

        • updated_at string Required
        • updated_by string Required
        • var_group_selections object

          Variable group selections. Maps var_group name to the selected option name within that group.

          Hide var_group_selections attribute Show var_group_selections attribute object
          • * string Additional properties

        • vars object

          Package level variable.

          Any of:
          object-1 object object-2 object

          Input/stream level variable. Refer to the integration documentation for more information.

        • version string

          Package policy ES version.

      • required_versions array[object] | null

        Not more than 100 elements.

        Hide required_versions attributes Show required_versions attributes object
        • percentage number Required

          Target percentage of agents to auto upgrade

          Minimum value is 0, maximum value is 100.

        • version string Required

          Target version for automatic agent upgrade

      • revision number Required
      • schema_version string
      • space_ids array[string]

        Not more than 100 elements.

      • status string Required

        Values are active or inactive.

      • supports_agentless boolean | null

        Indicates whether the agent policy supports agentless integrations.

        Default value is false.

      • unenroll_timeout number

        Minimum value is 0.

      • unprivileged_agents number
      • updated_at string Required
      • updated_by string Required
      • version string
  • 400 application/json

    Bad Request

    Hide response attributes Show response attributes object
    • attributes Required
    • error string
    • errorType string
    • message string Required
    • statusCode number
PUT /api/fleet/agent_policies/{agentPolicyId} 
curl \
 --request PUT 'https://localhost:5601/api/fleet/agent_policies/{agentPolicyId}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{"description":"An updated agent policy description","monitoring_enabled":["logs"],"name":"Updated agent policy","namespace":"default"}'
Request example
Update an agent policy 
{
  "description": "An updated agent policy description",
  "monitoring_enabled": [
    "logs"
  ],
  "name": "Updated agent policy",
  "namespace": "default"
}
Response examples (200)
The updated agent policy 
{
  "item": {
    "description": "An updated agent policy description",
    "id": "agent-policy-id-1",
    "is_managed": false,
    "is_protected": false,
    "name": "Updated agent policy",
    "namespace": "default",
    "revision": 2,
    "status": "active",
    "updated_at": "2024-01-15T11:00:00.000Z",
    "updated_by": "user1"
  }
}
Response examples (400)
Example of a generic error response 
{
  "error": "Bad Request",
  "message": "An error message describing what went wrong",
  "statusCode": 400
}