Create a service annotation

POST /api/apm/services/{serviceName}/annotation

Api key auth

Spaces method and path for this operation:

post /s/{space_id}/api/apm/services/{serviceName}/annotation

Refer to Spaces for more information.

Create a new annotation for a specific service.

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

Path parameters

serviceName string Required

The name of the service

application/json

Body Required

@timestamp string Required

The date and time of the annotation. It must be in ISO 8601 format.
message string

The message displayed in the annotation. It defaults to service.version.
service object Required

The service that identifies the configuration to create or update.
Hide service attributes Show service attributes object
- environment string
  
  The environment of the service.
- version string Required
  
  The version of the service.
tags array[string]

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.

Responses

200 application/json

Annotation created successfully
Hide response attributes Show response attributes object
- _id string
  
  Identifier
- _index string
  
  Index
- _source object
  
  Response
  
  Hide _source attributes Show _source attributes object
  
  @timestamp string
  
  annotation object
  
  Hide annotation attributes Show annotation attributes object
  
  title string
  
  type string
  
  event object
  
  Hide event attribute Show event attribute object
  
  created string
  
  message string
  
  service object
  
  Hide service attributes Show service attributes object
  
  environment string
  
  name string
  
  version string
  
  tags array[string]
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

POST /api/apm/services/{serviceName}/annotation

curl -X POST \
http://localhost:5601/api/apm/services/opbeans-java/annotation \
-H 'Content-Type: application/json' \
-H 'kbn-xsrf: true' \
-H 'Authorization: Basic YhUlubWZhM0FDbnlQeE6WRtaW49FQmSGZ4RUWXdX' \
-d '{
    "@timestamp": "2020-05-08T10:31:30.452Z",
    "service": {
        "version": "1.2"
    },
    "message": "Deployment 1.2"
    }'

Request example

Run `POST /api/apm/services/{serviceName}/annotation` to create a deployment annotation for a service.

{
  "@timestamp": "2024-01-15T12:00:00.000Z",
  "message": "Deployment 1.2.0",
  "service": {
    "environment": "production",
    "version": "1.2.0"
  },
  "tags": [
    "apm",
    "deployment"
  ]
}

Response examples (200)

An example of a successful response from `POST /api/apm/services/opbeans-java/annotation`, which creates an annotation for a service named `opbeans-java`.

{
  "_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
}

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
}