The Amplitude Chart Annotations API enables developers to programmatically create, retrieve, update, and delete annotations on Amplitude charts. Annotations mark significant events such as product releases, marketing campaigns, or incidents on timeline-based charts. This API allows teams to automate annotation management as part of their deployment or release pipelines, ensuring that important context is always visible alongside analytics data.
openapi: 3.1.0
info:
title: Amplitude Chart Annotations API
description: >-
The Amplitude Chart Annotations API enables developers to programmatically
create, retrieve, update, and delete annotations on Amplitude charts.
Annotations mark significant events such as product releases, marketing
campaigns, or incidents on timeline-based charts. This API allows teams
to automate annotation management as part of their deployment or release
pipelines, ensuring that important context is always visible alongside
analytics data.
version: '3'
contact:
name: Amplitude Support
url: https://amplitude.com/contact
termsOfService: https://amplitude.com/terms
externalDocs:
description: Amplitude Chart Annotations API Documentation
url: https://amplitude.com/docs/apis/analytics/chart-annotations
servers:
- url: https://amplitude.com
description: Amplitude Production Server
tags:
- name: Annotations
description: Chart annotation management operations
security:
- basicAuth: []
paths:
/api/3/annotations:
get:
operationId: listAnnotations
summary: Amplitude List All Annotations
description: >-
Retrieve all chart annotations in the project. Supports filtering by
category, chart, and date range.
tags:
- Annotations
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationListResponse'
examples:
listAnnotations200Example:
summary: Default listAnnotations 200 response
x-microcks-default: true
value:
data:
- example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createAnnotation
summary: Amplitude Create an Annotation
description: >-
Create a new chart annotation with a label, date or date range,
optional category, and optional chart association. Annotations appear
on timeline-based charts to provide context for significant events.
tags:
- Annotations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Annotation'
examples:
createAnnotation200Example:
summary: Default createAnnotation 200 response
x-microcks-default: true
value:
id: 100
label: example_value
date: '2025-03-15'
end_date: '2025-03-15'
details: example_value
category: example_value
chart_id: 100
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
'400':
description: Bad request - invalid annotation data
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/3/annotations/{annotation_id}:
get:
operationId: getAnnotation
summary: Amplitude Get an Annotation
description: >-
Retrieve a single chart annotation by its ID.
tags:
- Annotations
parameters:
- $ref: '#/components/parameters/annotationId'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Annotation'
examples:
getAnnotation200Example:
summary: Default getAnnotation 200 response
x-microcks-default: true
value:
id: 100
label: example_value
date: '2025-03-15'
end_date: '2025-03-15'
details: example_value
category: example_value
chart_id: 100
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
'401':
description: Unauthorized
'404':
description: Annotation not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateAnnotation
summary: Amplitude Update an Annotation
description: >-
Update an existing annotation. Only the fields included in the
request body are updated; other fields remain unchanged.
tags:
- Annotations
parameters:
- $ref: '#/components/parameters/annotationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAnnotationRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Annotation'
examples:
updateAnnotation200Example:
summary: Default updateAnnotation 200 response
x-microcks-default: true
value:
id: 100
label: example_value
date: '2025-03-15'
end_date: '2025-03-15'
details: example_value
category: example_value
chart_id: 100
created_at: '2025-03-15T14:30:00Z'
updated_at: '2025-03-15T14:30:00Z'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Annotation not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteAnnotation
summary: Amplitude Delete an Annotation
description: >-
Delete a chart annotation by its ID.
tags:
- Annotations
parameters:
- $ref: '#/components/parameters/annotationId'
responses:
'200':
description: Success
'401':
description: Unauthorized
'404':
description: Annotation not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
Use your Amplitude API key as the username and your secret key as the
password. Encode them as base64 in the format api_key:secret_key.
parameters:
annotationId:
name: annotation_id
in: path
required: true
description: >-
The unique identifier of the annotation.
schema:
type: integer
schemas:
AnnotationListResponse:
type: object
properties:
data:
type: array
description: >-
Array of annotation objects.
items:
$ref: '#/components/schemas/Annotation'
Annotation:
type: object
properties:
id:
type: integer
description: >-
The unique identifier of the annotation.
label:
type: string
description: >-
The display label for the annotation.
date:
type: string
format: date
description: >-
The start date of the annotation in YYYY-MM-DD format.
end_date:
type: string
format: date
description: >-
The end date of the annotation for date ranges. Null for
point-in-time annotations.
details:
type: string
description: >-
Additional details or notes for the annotation.
category:
type: string
description: >-
The category of the annotation for organization purposes.
chart_id:
type: integer
description: >-
The ID of the chart the annotation is associated with. Null for
project-wide annotations.
created_at:
type: string
format: date-time
description: >-
The timestamp when the annotation was created.
updated_at:
type: string
format: date-time
description: >-
The timestamp when the annotation was last updated.
CreateAnnotationRequest:
type: object
required:
- label
- date
properties:
label:
type: string
description: >-
The display label for the annotation.
maxLength: 255
date:
type: string
format: date
description: >-
The date of the annotation in YYYY-MM-DD format.
end_date:
type: string
format: date
description: >-
The end date for date-range annotations in YYYY-MM-DD format.
details:
type: string
description: >-
Additional details or notes for the annotation.
category:
type: string
description: >-
The category to assign to the annotation.
chart_id:
type: integer
description: >-
The ID of the chart to associate the annotation with. Omit for
project-wide annotations.
UpdateAnnotationRequest:
type: object
properties:
label:
type: string
description: >-
The updated display label for the annotation.
maxLength: 255
date:
type: string
format: date
description: >-
The updated date in YYYY-MM-DD format.
end_date:
type: string
format: date
description: >-
The updated end date in YYYY-MM-DD format.
details:
type: string
description: >-
Updated additional details or notes.
category:
type: string
description: >-
The updated category.
chart_id:
type: integer
description: >-
The updated chart ID.