Annotate visualizations in the APM app with significant events. Annotations enable you to easily see how events are impacting the performance of your applications.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/elk-stack:elk-stack-apm-annotations-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
contact:
name: Kibana Team
description: The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
title: Kibana 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:**
post /s/{space_id}/api/apm/services/{serviceName}/annotation
Refer to 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:
examples:
badRequestResponse:
$ref: '#/components/examples/APM_UI_error_400_response'
schema:
$ref: '#/components/schemas/APM_UI_400_response'
description: Bad Request response
'401':
content:
application/json:
examples:
unauthorizedResponse:
$ref: '#/components/examples/APM_UI_error_401_response'
schema:
$ref: '#/components/schemas/APM_UI_401_response'
description: Unauthorized response
'403':
content:
application/json:
examples:
forbiddenResponse:
$ref: '#/components/examples/APM_UI_error_403_response'
schema:
$ref: '#/components/schemas/APM_UI_403_response'
description: Forbidden response
'404':
content:
application/json:
examples:
notFoundResponse:
$ref: '#/components/examples/APM_UI_error_404_response'
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:**
get /s/{space_id}/api/apm/services/{serviceName}/annotation/search
Refer to 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:
examples:
getAnnotationResponse1:
$ref: '#/components/examples/APM_UI_annotation_search_get_200_response1'
schema:
$ref: '#/components/schemas/APM_UI_annotation_search_response'
description: Successful response
'400':
content:
application/json:
examples:
badRequestResponse:
$ref: '#/components/examples/APM_UI_error_400_response'
schema:
$ref: '#/components/schemas/APM_UI_400_response'
description: Bad Request response
'401':
content:
application/json:
examples:
unauthorizedResponse:
$ref: '#/components/examples/APM_UI_error_401_response'
schema:
$ref: '#/components/schemas/APM_UI_401_response'
description: Unauthorized response
'500':
content:
application/json:
examples:
internalServerErrorResponse:
$ref: '#/components/examples/APM_UI_error_500_response'
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:
examples:
APM_UI_error_403_response:
description: An example of a 403 Forbidden response, returned when the authenticated user lacks the required APM and User Experience privileges.
value:
error: Forbidden
message: Insufficient privileges to perform this action. The APM and User Experience feature requires `all` privileges.
statusCode: 403
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_error_500_response:
description: An example of a 500 Internal Server Error response, returned when an unexpected error occurs while processing the request.
value:
error: Internal Server Error
message: An internal server error occurred. Check the Kibana server logs for details.
statusCode: 500
APM_UI_error_401_response:
description: An example of a 401 Unauthorized response, returned when the request is missing valid authentication credentials.
value:
error: Unauthorized
message: '[security_exception]: missing authentication credentials for REST request'
statusCode: 401
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
APM_UI_annotation_search_get_200_response1:
description: An example of a successful response from `GET /api/apm/services/{serviceName}/annotation/search`, which returns the annotations associated with a service over the given time range.
value:
annotations:
- '@timestamp': 1735689600000
id: opbeans-node@2.0.0
text: opbeans-node@2.0.0
type: version
- '@timestamp': 1736294400000
id: opbeans-node@2.1.0
text: opbeans-node@2.1.0
type: version
APM_UI_error_400_response:
description: An example of a 400 Bad Request response, returned when the request payload or query parameters fail validation.
value:
error: Bad Request
message: '[request body]: expected value of type [string] but got [undefined]'
statusCode: 400
APM_UI_error_404_response:
description: 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.
value:
error: Not Found
message: Not Found
statusCode: 404
schemas:
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
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_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_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_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_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_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_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
parameters:
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
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
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"