openapi: 3.1.0
info:
  title: Amplitude Attribution Annotations Event Categories 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: Event Categories
  description: Operations for managing event categories
paths:
  /api/2/taxonomy/category:
    get:
      operationId: listEventCategories
      summary: Amplitude List All Event Categories
      description: Retrieve all event categories in the project. Categories help organize event types into logical groups for easier data governance.
      tags:
      - Event Categories
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryListResponse'
              examples:
                listEventCategories200Example:
                  summary: Default listEventCategories 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - example_value
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createEventCategory
      summary: Amplitude Create an Event Category
      description: Create a new event category to organize event types into logical groups.
      tags:
      - Event Categories
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - category_name
              properties:
                category_name:
                  type: string
                  description: The name of the event category.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                createEventCategory200Example:
                  summary: Default createEventCategory 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '409':
          description: Category already exists
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/2/taxonomy/category/{category_id}:
    get:
      operationId: getEventCategory
      summary: Amplitude Get an Event Category
      description: Retrieve a single event category by its ID.
      tags:
      - Event Categories
      parameters:
      - $ref: '#/components/parameters/categoryId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
              examples:
                getEventCategory200Example:
                  summary: Default getEventCategory 200 response
                  x-microcks-default: true
                  value:
                    id: 100
                    name: Example Name
        '401':
          description: Unauthorized
        '404':
          description: Category not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateEventCategory
      summary: Amplitude Update an Event Category
      description: Update the name of an existing event category.
      tags:
      - Event Categories
      parameters:
      - $ref: '#/components/parameters/categoryId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - category_name
              properties:
                category_name:
                  type: string
                  description: The new name for the event category.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                updateEventCategory200Example:
                  summary: Default updateEventCategory 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '401':
          description: Unauthorized
        '404':
          description: Category not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteEventCategory
      summary: Amplitude Delete an Event Category
      description: Delete an event category. Event types previously assigned to this category will become uncategorized.
      tags:
      - Event Categories
      parameters:
      - $ref: '#/components/parameters/categoryId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              examples:
                deleteEventCategory200Example:
                  summary: Default deleteEventCategory 200 response
                  x-microcks-default: true
                  value:
                    success: true
        '401':
          description: Unauthorized
        '404':
          description: Category not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Category:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the category.
        name:
          type: string
          description: The name of the category.
    CategoryListResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of event categories.
          items:
            $ref: '#/components/schemas/Category'
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful.
  parameters:
    categoryId:
      name: category_id
      in: path
      required: true
      description: The ID of the event category.
      schema:
        type: integer
externalDocs:
  description: Amplitude Attribution API Documentation
  url: https://amplitude.com/docs/apis/analytics/attribution