Kibana APM agent configuration API

openapi: 3.0.3
info:
  contact:
    name: Kibana Team
  description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.

    The API calls are stateless.

    Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the

    request.

    API requests return JSON output, which is a format that is machine-readable and works well for automation.


    To interact with Kibana APIs, use the following operations:


    - GET: Fetches the information.

    - PATCH: Applies partial modifications to the existing information.

    - POST: Adds new information.

    - PUT: Updates the existing information.

    - DELETE: Removes the information.


    You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.

    For example:


    ```

    GET kbn:/api/data_views

    ```


    For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).


    NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.


    ## Documentation source and versions


    This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.

    It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).


    This documentation contains work-in-progress information for future Elastic Stack releases.

    '
  title: Kibana APIs Actions APM agent configuration API
  version: ''
  x-doc-license:
    name: Attribution-NonCommercial-NoDerivatives 4.0 International
    url: https://creativecommons.org/licenses/by-nc-nd/4.0/
  x-feedbackLink:
    label: Feedback
    url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
  variables:
    kibana_url:
      default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- description: 'Adjust APM agent configuration without need to redeploy your application.

    '
  name: APM agent configuration
paths:
  /api/apm/settings/agent-configuration:
    delete:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb delete">delete</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Delete an existing agent configuration. You must have `all` privileges for the APM and User Experience feature in Kibana. When successful, the configuration is removed and, if Fleet is enabled, APM package policies are synchronized accordingly.

        '
      operationId: deleteAgentConfiguration
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - $ref: '#/components/parameters/APM_UI_kbn_xsrf'
      requestBody:
        content:
          application/json:
            examples:
              deleteAgentConfigurationRequest1:
                $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_delete_request1'
            schema:
              $ref: '#/components/schemas/APM_UI_delete_service_object'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                deleteAgentConfigurationResponseExample1:
                  $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_delete_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_delete_agent_configurations_response'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_403_response'
          description: Forbidden response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Delete agent configuration
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Retrieve all agent configurations. You must have `read` privileges for the APM and User Experience feature in Kibana. If agent configuration is not available on the current deployment, the API returns a 404.

        '
      operationId: getAgentConfigurations
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      responses:
        '200':
          content:
            application/json:
              examples:
                getAgentConfigurationsResponseExample1:
                  $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_get_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_agent_configurations_response'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Get a list of agent configurations
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
    put:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb put">put</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-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.

        '
      operationId: createUpdateAgentConfiguration
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - $ref: '#/components/parameters/APM_UI_kbn_xsrf'
      - description: If the config exists ?overwrite=true is required
        in: query
        name: overwrite
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            examples:
              createUpdateAgentConfigurationRequestExample1:
                $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_put_request1'
            schema:
              $ref: '#/components/schemas/APM_UI_agent_configuration_intake_object'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                createUpdateAgentConfigurationResponseExample1:
                  $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_put_200_response1'
              schema:
                additionalProperties: false
                description: The response body is intentionally empty for this endpoint.
                type: object
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_403_response'
          description: Forbidden response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Create or update agent configuration
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/apm/settings/agent-configuration/agent_name:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration/agent_name</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Retrieve `agentName` for a service.'
      operationId: getAgentNameForService
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - description: The name of the service
        example: node
        in: query
        name: serviceName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_service_agent_name_response'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Get agent name for service
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/apm/settings/agent-configuration/environments:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration/environments</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Retrieve the available environments for a given service, to be used in agent configuration. You must have `read` privileges for the APM and User Experience feature in Kibana. If `serviceName` is omitted, environments across all services are returned.

        '
      operationId: getEnvironmentsForService
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - description: The name of the service. If omitted, environments across all services are returned.
        example: opbeans-node
        in: query
        name: serviceName
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                getEnvironmentsForServiceResponseExample1:
                  $ref: '#/components/examples/APM_UI_agent_configuration_environments_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_service_environments_response'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Get environments for service
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/apm/settings/agent-configuration/search:
    post:
      deprecated: true
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb post">post</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration/search</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        DEPRECATED: This endpoint is intended for internal use by APM agents to fetch their configuration and mark it as applied. Do not use for new integrations. It searches for a single agent configuration matching the given service, and optionally updates the `applied_by_agent` field when the provided `etag` matches the current configuration.

        '
      operationId: searchSingleConfiguration
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - $ref: '#/components/parameters/APM_UI_kbn_xsrf'
      requestBody:
        content:
          application/json:
            examples:
              searchSingleConfigurationRequest1:
                $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_search_request1'
            schema:
              $ref: '#/components/schemas/APM_UI_search_agent_configuration_object'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                searchSingleConfigurationResponse1:
                  $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_search_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_search_agent_configuration_response'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Lookup single agent configuration
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/apm/settings/agent-configuration/view:
    get:
      description: '**Spaces method and path for this operation:**


        <div><span class="operation-verb get">get</span>&nbsp;<span class="operation-path">/s/{space_id}/api/apm/settings/agent-configuration/view</span></div>


        Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.


        Retrieve a single agent configuration matching the given service name and environment. You must have `read` privileges for the APM and User Experience feature in Kibana. If no matching configuration is found, the API returns a 404.

        '
      operationId: getSingleAgentConfiguration
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - description: Service name
        example: node
        in: query
        name: name
        schema:
          type: string
      - description: Service environment
        example: prod
        in: query
        name: environment
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                getSingleAgentConfigurationResponseExample1:
                  $ref: '#/components/examples/APM_UI_agent_configuration_intake_object_view_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_single_agent_configuration_response'
          description: Successful response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_400_response'
          description: Bad Request response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_401_response'
          description: Unauthorized response
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_404_response'
          description: Not found response
      summary: Get single agent configuration
      tags:
      - APM agent configuration
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  examples:
    APM_UI_agent_configuration_intake_object_search_200_response1:
      description: An example of a successful response from `POST /api/apm/settings/agent-configuration/search`.
      value:
        _id: CIaqXXABmQCdPphWj8EJ
        _index: .apm-agent-configuration
        _score: 2
        _source:
          '@timestamp': 1582031336265
          agent_name: nodejs
          applied_by_agent: false
          etag: 5080ed25785b7b19f32713681e79f46996801a5b
          service:
            name: frontend
          settings:
            transaction_sample_rate: '1'
    APM_UI_agent_configuration_intake_object_delete_200_response1:
      description: An example of a successful response from `DELETE /api/apm/settings/agent-configuration`.
      value:
        result: deleted
    APM_UI_agent_configuration_intake_object_search_request1:
      description: Run `POST /api/apm/settings/agent-configuration/search` to search configuration details.
      value:
        etag: 1e58c178efeebae15c25c539da740d21dee422fc
        service:
          environment: production
          name: frontend
    APM_UI_agent_configuration_environments_200_response1:
      description: An example of a successful response from `GET /api/apm/settings/agent-configuration/environments`.
      value:
        environments:
        - alreadyConfigured: true
          name: production
        - alreadyConfigured: false
          name: development
        - alreadyConfigured: false
          name: ALL_OPTION_VALUE
    APM_UI_agent_configuration_intake_object_delete_request1:
      description: Run `DELETE /api/apm/settings/agent-configuration` to delete a configuration.
      value:
        service:
          environment: production
          name: frontend
    APM_UI_agent_configuration_intake_object_view_200_response1:
      description: An example of a successful response from `GET /api/apm/settings/agent-configuration/view`.
      value:
        '@timestamp': 1582031336265
        agent_name: nodejs
        applied_by_agent: true
        etag: 5080ed25785b7b19f32713681e79f46996801a5b
        id: CIaqXXABmQCdPphWj8EJ
        service:
          environment: production
          name: frontend
        settings:
          capture_body: 'off'
          transaction_max_spans: '500'
          transaction_sample_rate: '0.4'
    APM_UI_agent_configuration_intake_object_put_request1:
      description: Run `PUT /api/apm/settings/agent-configuration` to create or update configuration details.
      value:
        agent_name: nodejs
        service:
          environment: production
          name: frontend
        settings:
          capture_body: 'off'
          transaction_max_spans: '500'
          transaction_sample_rate: '0.4'
    APM_UI_agent_configuration_intake_object_get_200_response1:
      description: An example of a successful response from `GET /api/apm/settings/agent-configuration`.
      value:
      - '@timestamp': 1581934104843
        agent_name: go
        applied_by_agent: false
        etag: 1e58c178efeebae15c25c539da740d21dee422fc
        service:
          environment: production
          name: opbeans-go
        settings:
          capture_body: 'off'
          transaction_max_spans: '200'
          transaction_sample_rate: '1'
      - '@timestamp': 1581934111727
        agent_name: go
        applied_by_agent: false
        etag: 3eed916d3db434d9fb7f039daa681c7a04539a64
        service:
          name: opbeans-go
        settings:
          capture_body: 'off'
          transaction_max_spans: '300'
          transaction_sample_rate: '1'
      - '@timestamp': 1582031336265
        agent_name: nodejs
        applied_by_agent: false
        etag: 5080ed25785b7b19f32713681e79f46996801a5b
        service:
          name: frontend
        settings:
          transaction_sample_rate: '1'
    APM_UI_agent_configuration_intake_object_put_200_response1:
      description: An example of a successful response from `PUT /api/apm/settings/agent-configuration`. The response body is intentionally empty.
      value: {}
  schemas:
    APM_UI_single_agent_configuration_response:
      allOf:
      - type: object
        properties:
          id:
            type: string
        required:
        - id
      - $ref: '#/components/schemas/APM_UI_agent_configuration_object'
    APM_UI_service_agent_name_response:
      type: object
      properties:
        agentName:
          description: Agent name
          example: nodejs
          type: string
    APM_UI_401_response:
      type: object
      properties:
        error:
          description: Error type
          example: Unauthorized
          type: string
        message:
          description: Error message
          type: string
        statusCode:
          description: Error status code
          example: 401
          type: number
    APM_UI_search_agent_configuration_response:
      type: object
      properties:
        _id:
          description: Identifier
          type: string
        _index:
          description: Index
          type: string
        _score:
          description: Score
          type: number
        _source:
          $ref: '#/components/schemas/APM_UI_agent_configuration_object'
    APM_UI_agent_configurations_response:
      type: object
      properties:
        configurations:
          description: Agent configuration
          items:
            $ref: '#/components/schemas/APM_UI_agent_configuration_object'
          type: array
    APM_UI_agent_configuration_intake_object:
      type: object
      properties:
        agent_name:
          description: The agent name is used by the UI to determine which settings to display.
          type: string
        service:
          $ref: '#/components/schemas/APM_UI_service_object'
        settings:
          $ref: '#/components/schemas/APM_UI_settings_object'
      required:
      - service
      - settings
    APM_UI_403_response:
      type: object
      properties:
        error:
          description: Error type
          example: Forbidden
          type: string
        message:
          description: Error message
          type: string
        statusCode:
          description: Error status code
          example: 403
          type: number
    APM_UI_delete_agent_configurations_response:
      type: object
      properties:
        result:
          description: Result
          type: string
    APM_UI_settings_object:
      additionalProperties:
        type: string
      description: Agent configuration settings
      type: object
    APM_UI_agent_configuration_object:
      description: Agent configuration
      type: object
      properties:
        '@timestamp':
          description: Timestamp
          example: 1730194190636
          type: number
        agent_name:
          description: Agent name
          type: string
        applied_by_agent:
          description: Applied by agent
          example: true
          type: boolean
        etag:
          description: '`etag` is sent by the APM agent to indicate the `etag` of the last successfully applied configuration. If the `etag` matches an existing configuration its `applied_by_agent` property will be set to `true`. Every time a configuration is edited `applied_by_agent` is reset to `false`.

            '
          example: 0bc3b5ebf18fba8163fe4c96f491e3767a358f85
          type: string
        service:
          $ref: '#/components/schemas/APM_UI_service_object'
        settings:
          $ref: '#/components/schemas/APM_UI_settings_object'
      required:
      - service
      - settings
      - '@timestamp'
      - etag
    APM_UI_search_agent_configuration_object:
      type: object
      properties:
        error:
          description: 'If provided, the agent configuration will be marked as error and `applied_by_agent` will be set to `false`.

            This is useful for cases where the agent configuration was not applied successfully.

            '
          type: string
        etag:
          description: If etags match then `applied_by_agent` field will be set to `true`
          example: 0bc3b5ebf18fba8163fe4c96f491e3767a358f85
          type: string
        mark_as_applied_by_agent:
          description: '`markAsAppliedByAgent=true` means "force setting it to true regardless of etag".

            This is needed for Jaeger agent that doesn''t have etags

            '
          type: boolean
        service:
          $ref: '#/components/schemas/APM_UI_service_object'
      required:
      - service
    APM_UI_service_object:
      description: Service
      type: object
      properties:
        environment:
          description: The environment of the service.
          example: prod
          type: string
        name:
          description: The name of the service.
          example: node
          type: string
    APM_UI_service_environments_response:
      type: object
      properties:
        environments:
          description: Service environment list
          items:
            $ref: '#/components/schemas/APM_UI_service_environment_object'
          type: array
    APM_UI_service_environment_object:
      type: object
      properties:
        alreadyConfigured:
          description: Already configured
          type: boolean
        name:
          description: Service environment name
          example: ALL_OPTION_VALUE
          type: string
    APM_UI_delete_service_object:
      description: Service
      type: object
      properties:
        service:
          $ref: '#/components/schemas/APM_UI_service_object'
      required:
      - service
    APM_UI_404_response:
      type: object
      properties:
        error:
          description: Error type
          example: Not Found
          type: string
        message:
          description: Error message
          example: Not Found
          type: string
        statusCode:
          description: Error status code
          example: 404
          type: number
    APM_UI_400_response:
      type: object
      properties:
        error:
          description: Error type
          example: Not Found
          type: string
        message:
          description: Error message
          example: Not Found
          type: string
        statusCode:
          description: Error status code
          example: 400
          type: number
  parameters:
    APM_UI_kbn_xsrf:
      description: A required header to protect against CSRF attacks
      in: header
      name: kbn-xsrf
      required: true
      schema:
        example: 'true'
        type: string
    APM_UI_elastic_api_version:
      description: The version of the API to use
      in: header
      name: elastic-api-version
      required: true
      schema:
        default: '2023-10-31'
        enum:
        - '2023-10-31'
        type: string
  securitySchemes:
    apiKeyAuth:
      description: 'These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: `Authorization: ApiKey base64AccessApiKey`

        '
      in: header
      name: Authorization
      type: apiKey
    basicAuth:
      scheme: basic
      type: http
x-topics:
- title: Kibana spaces
  content: "Spaces enable you to organize your dashboards and other saved objects into meaningful categories.\nYou can use the default space or create your own spaces.\n\nTo run APIs in non-default spaces, you must add `s/{space_id}/` to the path.\nFor example:\n\n```bash\ncurl -X GET \"http://${KIBANA_URL}/s/marketing/api/data_views\" \\\n  -H \"Authorization: ApiKey ${API_KEY}\"\n```\n\nIf you use the Kibana console to send API requests, it automatically adds the appropriate space identifier.\n\nTo learn more, check out [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces).\n"