Amplitude Annotations API

openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations API
  description: The Amplitude Attribution API allows developers to send attribution campaign events to Amplitude from ad networks, attribution providers, or custom marketing tools. It associates users with the campaigns, channels, and creatives that drove their acquisition or re-engagement. This API is used to enrich Amplitude user profiles with marketing attribution data for campaign performance analysis and ROI measurement.
  version: '2'
  contact:
    name: Amplitude Support
    url: https://amplitude.com/contact
  termsOfService: https://amplitude.com/terms
servers:
- url: https://api2.amplitude.com
  description: Amplitude US Production Server
- url: https://api.eu.amplitude.com
  description: Amplitude EU Production Server
security: []
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:
    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.
    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'
  parameters:
    annotationId:
      name: annotation_id
      in: path
      required: true
      description: The unique identifier of the annotation.
      schema:
        type: integer
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution