PUT /api/apm/settings/agent-configuration
Api key auth

Spaces method and path for this operation:

put /s/{space_id}/api/apm/settings/agent-configuration

Refer to Spaces for more information.

Create or update an agent configuration. You must have all privileges for the APM and User Experience feature in Kibana. When updating an existing configuration, the ?overwrite=true query parameter is required. If the configuration already exists and overwrite is not set to true, the API returns a 400 error. When successful and Fleet is enabled, APM package policies are synchronized accordingly.

Headers

  • elastic-api-version string Required

    The version of the API to use

    Value is 2023-10-31. Default value is 2023-10-31.

  • kbn-xsrf string Required

    A required header to protect against CSRF attacks

Query parameters

  • overwrite boolean

    If the config exists ?overwrite=true is required

application/json

Body Required

  • agent_name string

    The agent name is used by the UI to determine which settings to display.

  • service object Required

    Service

    Hide service attributes Show service attributes object
    • environment string

      The environment of the service.

    • name string

      The name of the service.

  • settings object Required

    Agent configuration settings

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

Responses

  • 200 application/json

    Successful response

    The response body is intentionally empty for this endpoint.

    Additional properties are NOT allowed.
  • 400 application/json

    Bad Request response

    Hide response attributes Show response attributes object
    • error string

      Error type

    • message string

      Error message

    • statusCode number

      Error status code
  • 401 application/json

    Unauthorized response

    Hide response attributes Show response attributes object
    • error string

      Error type

    • message string

      Error message

    • statusCode number

      Error status code
  • 403 application/json

    Forbidden response

    Hide response attributes Show response attributes object
    • error string

      Error type

    • message string

      Error message

    • statusCode number

      Error status code
  • 404 application/json

    Not found response

    Hide response attributes Show response attributes object
    • error string

      Error type

    • message string

      Error message

    • statusCode number

      Error status code
PUT /api/apm/settings/agent-configuration 
curl \
 --request PUT 'https://<KIBANA_URL>/api/apm/settings/agent-configuration' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "elastic-api-version: 2023-10-31" \
 --header "kbn-xsrf: true" \
 --data '{"agent_name":"nodejs","service":{"environment":"production","name":"frontend"},"settings":{"capture_body":"off","transaction_max_spans":"500","transaction_sample_rate":"0.4"}}'
Request example
Run `PUT /api/apm/settings/agent-configuration` to create or update configuration details. 
{
  "agent_name": "nodejs",
  "service": {
    "environment": "production",
    "name": "frontend"
  },
  "settings": {
    "capture_body": "off",
    "transaction_max_spans": "500",
    "transaction_sample_rate": "0.4"
  }
}
Response examples (200)
An example of a successful response from `PUT /api/apm/settings/agent-configuration`. The response body is intentionally empty. 
{
  "$ref": "#/components/examples/APM_UI_agent_configuration_intake_object_put_200_response1"
}
Response examples (400)
An example of a 400 Bad Request response, returned when the request payload or query parameters fail validation. 
{
  "error": "Bad Request",
  "message": "[request body]: expected value of type [string] but got [undefined]",
  "statusCode": 400
}
Response examples (401)
An example of a 401 Unauthorized response, returned when the request is missing valid authentication credentials. 
{
  "error": "Unauthorized",
  "message": "[security_exception]: missing authentication credentials for REST request",
  "statusCode": 401
}
Response examples (403)
An example of a 403 Forbidden response, returned when the authenticated user lacks the required APM and User Experience privileges. 
{
  "error": "Forbidden",
  "message": "Insufficient privileges to perform this action. The APM and User Experience feature requires `all` privileges.",
  "statusCode": 403
}
Response examples (404)
An example of a 404 Not Found response, returned when the requested resource does not exist or the feature is not available on the current deployment. 
{
  "error": "Not Found",
  "message": "Not Found",
  "statusCode": 404
}