Amplitude

Amplitude Annotations API

Chart annotation management operations

Documentation GitHub OpenAPI

Operations 5

GET /api/3/annotations Amplitude List All Annotations #

POST /api/3/annotations Amplitude Create an Annotation #

GET /api/3/annotations/{annotation_id} Amplitude Get an Annotation #

PUT /api/3/annotations/{annotation_id} Amplitude Update an Annotation #

DELETE /api/3/annotations/{annotation_id} Amplitude Delete an Annotation #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

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.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/amplitude-annotations-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

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.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.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
servers:
- url: https://amplitude.com
  description: Amplitude Production Server
security:
- basicAuth: []
tags:
- name: Annotations
  description: Chart annotation management operations
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:
  schemas:
    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.
    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.
    AnnotationListResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of annotation objects.
          items:
            $ref: '#/components/schemas/Annotation'
    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.
  parameters:
    annotationId:
      name: annotation_id
      in: path
      required: true
      description: The unique identifier of the annotation.
      schema:
        type: integer
  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.
externalDocs:
  description: Amplitude Chart Annotations API Documentation
  url: https://amplitude.com/docs/apis/analytics/chart-annotations