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.