Kibana APM annotations 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 annotations 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: 'Annotate visualizations in the APM app with significant events. Annotations enable you to easily see how events are impacting the performance of your applications.

    '
  name: APM annotations
paths:
  /api/apm/services/{serviceName}/annotation:
    post:
      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/services/{serviceName}/annotation</span></div>


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


        Create a new annotation for a specific service.'
      operationId: createAnnotation
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - $ref: '#/components/parameters/APM_UI_kbn_xsrf'
      - description: The name of the service
        in: path
        name: serviceName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            examples:
              createAnnotationRequest1:
                $ref: '#/components/examples/APM_UI_annotation_object_post_request1'
            schema:
              $ref: '#/components/schemas/APM_UI_create_annotation_object'
        required: true
      responses:
        '200':
          content:
            application/json:
              examples:
                createAnnotationResponse1:
                  $ref: '#/components/examples/APM_UI_annotation_object_post_200_response1'
              schema:
                $ref: '#/components/schemas/APM_UI_create_annotation_response'
          description: Annotation created successfully
        '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 a service annotation
      tags:
      - APM annotations
      x-codeSamples:
      - lang: Curl
        source: "curl -X POST \\\nhttp://localhost:5601/api/apm/services/opbeans-java/annotation \\\n-H 'Content-Type: application/json' \\\n-H 'kbn-xsrf: true' \\\n-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \\\n-d '{\n    \"@timestamp\": \"2020-05-08T10:31:30.452Z\",\n    \"service\": {\n        \"version\": \"1.2\"\n    },\n    \"message\": \"Deployment 1.2\"\n    }'\n"
      x-metaTags:
      - content: Kibana
        name: product_name
  /api/apm/services/{serviceName}/annotation/search:
    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/services/{serviceName}/annotation/search</span></div>


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


        Search for annotations related to a specific service.'
      operationId: getAnnotation
      parameters:
      - $ref: '#/components/parameters/APM_UI_elastic_api_version'
      - description: The name of the service
        in: path
        name: serviceName
        required: true
        schema:
          type: string
      - description: The environment to filter annotations by
        in: query
        name: environment
        required: false
        schema:
          type: string
      - description: The start date for the search
        example: '2024-01-01T00:00:00.000Z'
        in: query
        name: start
        required: false
        schema:
          format: date-time
          type: string
      - description: The end date for the search
        example: '2024-01-31T23:59:59.999Z'
        in: query
        name: end
        required: false
        schema:
          format: date-time
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_annotation_search_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
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APM_UI_500_response'
          description: Internal Server Error response
      summary: Search for annotations
      tags:
      - APM annotations
      x-metaTags:
      - content: Kibana
        name: product_name
components:
  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
  schemas:
    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_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_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_500_response:
      type: object
      properties:
        error:
          description: Error type
          example: Internal Server Error
          type: string
        message:
          description: Error message
          type: string
        statusCode:
          description: Error status code
          example: 500
          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
    APM_UI_create_annotation_response:
      type: object
      properties:
        _id:
          description: Identifier
          type: string
        _index:
          description: Index
          type: string
        _source:
          description: Response
          type: object
          properties:
            '@timestamp':
              type: string
            annotation:
              type: object
              properties:
                title:
                  type: string
                type:
                  type: string
            event:
              type: object
              properties:
                created:
                  type: string
            message:
              type: string
            service:
              type: object
              properties:
                environment:
                  type: string
                name:
                  type: string
                version:
                  type: string
            tags:
              items:
                type: string
              type: array
    APM_UI_create_annotation_object:
      type: object
      properties:
        '@timestamp':
          description: The date and time of the annotation. It must be in ISO 8601 format.
          type: string
        message:
          description: The message displayed in the annotation. It defaults to `service.version`.
          type: string
        service:
          description: The service that identifies the configuration to create or update.
          type: object
          properties:
            environment:
              description: The environment of the service.
              type: string
            version:
              description: The version of the service.
              type: string
          required:
          - version
        tags:
          description: 'Tags are used by the Applications UI to distinguish APM annotations from other annotations. Tags may have additional functionality in future releases. It defaults to `[apm]`. While you can add additional tags, you cannot remove the `apm` tag.

            '
          items:
            type: string
          type: array
      required:
      - '@timestamp'
      - service
    APM_UI_annotation_search_response:
      type: object
      properties:
        annotations:
          description: Annotations
          items:
            type: object
            properties:
              '@timestamp':
                type: number
              id:
                type: string
              text:
                type: string
              type:
                enum:
                - version
                type: string
          type: array
  examples:
    APM_UI_annotation_object_post_200_response1:
      description: An example of a successful response from `POST /api/apm/services/opbeans-java/annotation`, which creates an annotation for a service named `opbeans-java`.
      value:
        _id: Lc9I93EBh6DbmkeV7nFX
        _index: observability-annotations
        _primary_term: 1
        _seq_no: 12
        _source:
          '@timestamp': '2020-05-08T10:31:30.452Z'
          annotation:
            type: deployment
          event:
            created: '2020-05-09T02:34:43.937Z'
          message: Deployment 1.2
          service:
            name: opbeans-java
            version: '1.2'
          tags:
          - apm
          - elastic.co
          - customer
        _version: 1
        found: true
    APM_UI_annotation_object_post_request1:
      description: Run `POST /api/apm/services/{serviceName}/annotation` to create a deployment annotation for a service.
      value:
        '@timestamp': '2024-01-15T12:00:00.000Z'
        message: Deployment 1.2.0
        service:
          environment: production
          version: 1.2.0
        tags:
        - apm
        - deployment
  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"