The Amplitude Taxonomy API provides programmatic management of your analytics tracking plan. It supports creating, reading, updating, and deleting event categories, event types, event properties, and user properties. This API is essential for data governance workflows, enabling teams to maintain a consistent and well-organized event taxonomy across their instrumentation without needing to use the Amplitude UI directly.
openapi: 3.1.0
info:
title: Amplitude Taxonomy API
description: >-
The Amplitude Taxonomy API provides programmatic management of your
analytics tracking plan. It supports creating, reading, updating, and
deleting event categories, event types, event properties, and user
properties. This API is essential for data governance workflows, enabling
teams to maintain a consistent and well-organized event taxonomy across
their instrumentation without needing to use the Amplitude UI directly.
version: '2'
contact:
name: Amplitude Support
url: https://amplitude.com/contact
termsOfService: https://amplitude.com/terms
externalDocs:
description: Amplitude Taxonomy API Documentation
url: https://amplitude.com/docs/apis/analytics/taxonomy
servers:
- url: https://amplitude.com
description: Amplitude Production Server
tags:
- name: Event Categories
description: Operations for managing event categories
- name: Event Properties
description: Operations for managing event properties
- name: Event Types
description: Operations for managing event types
- name: User Properties
description: Operations for managing user properties
security:
- basicAuth: []
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
/api/2/taxonomy/event:
get:
operationId: listEventTypes
summary: Amplitude List All Event Types
description: >-
Retrieve all event types in the project. Optionally include deleted
event types using the showDeleted parameter.
tags:
- Event Types
parameters:
- name: showDeleted
in: query
description: >-
When true, include deleted event types in the response.
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventTypeListResponse'
examples:
listEventTypes200Example:
summary: Default listEventTypes 200 response
x-microcks-default: true
value:
data:
- example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createEventType
summary: Amplitude Create an Event Type
description: >-
Create a new event type in the tracking plan. This is for planning
purposes and does not affect event ingestion.
tags:
- Event Types
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- event_type
properties:
event_type:
type: string
description: >-
The name of the event type.
category:
type: string
description: >-
The category to assign the event type to.
description:
type: string
description: >-
A description of the event type.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
createEventType200Example:
summary: Default createEventType 200 response
x-microcks-default: true
value:
success: true
'400':
description: Bad request
'401':
description: Unauthorized
'409':
description: Event type already exists
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/taxonomy/event/{event_type}:
get:
operationId: getEventType
summary: Amplitude Get an Event Type
description: >-
Retrieve a single event type by its name.
tags:
- Event Types
parameters:
- $ref: '#/components/parameters/eventType'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventType'
examples:
getEventType200Example:
summary: Default getEventType 200 response
x-microcks-default: true
value:
event_type: standard
category:
id: {}
name: {}
description: Example description text
'401':
description: Unauthorized
'404':
description: Event type not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateEventType
summary: Amplitude Update an Event Type
description: >-
Update an existing event type's metadata such as description or
category assignment.
tags:
- Event Types
parameters:
- $ref: '#/components/parameters/eventType'
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
new_event_type:
type: string
description: >-
The new name for the event type.
category:
type: string
description: >-
The category to assign the event type to.
description:
type: string
description: >-
An updated description of the event type.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
updateEventType200Example:
summary: Default updateEventType 200 response
x-microcks-default: true
value:
success: true
'401':
description: Unauthorized
'404':
description: Event type not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteEventType
summary: Amplitude Delete an Event Type
description: >-
Delete a planned event type. This is intended for removing event
types that have not yet received data. Deleting an event type that
has received data does not remove the data.
tags:
- Event Types
parameters:
- $ref: '#/components/parameters/eventType'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
deleteEventType200Example:
summary: Default deleteEventType 200 response
x-microcks-default: true
value:
success: true
'401':
description: Unauthorized
'404':
description: Event type not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/taxonomy/event-property:
get:
operationId: listEventProperties
summary: Amplitude List All Event Properties
description: >-
Retrieve all event properties for a given event type in the project.
tags:
- Event Properties
parameters:
- name: event_type
in: query
required: true
description: >-
The event type to list properties for.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventPropertyListResponse'
examples:
listEventProperties200Example:
summary: Default listEventProperties 200 response
x-microcks-default: true
value:
data:
- example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createEventProperty
summary: Amplitude Create an Event Property
description: >-
Create a new event property in the tracking plan for a specific
event type.
tags:
- Event Properties
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- event_type
- event_property
properties:
event_type:
type: string
description: >-
The event type this property belongs to.
event_property:
type: string
description: >-
The name of the event property.
description:
type: string
description: >-
A description of the event property.
type:
type: string
description: >-
The data type of the property.
enum:
- string
- number
- boolean
- enum
- any
is_required:
type: boolean
description: >-
Whether the property is required.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
createEventProperty200Example:
summary: Default createEventProperty 200 response
x-microcks-default: true
value:
success: true
'400':
description: Bad request
'401':
description: Unauthorized
'409':
description: Event property already exists
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/taxonomy/event-property/{event_property}:
get:
operationId: getEventProperty
summary: Amplitude Get an Event Property
description: >-
Retrieve a single event property by its name for a given event type.
tags:
- Event Properties
parameters:
- name: event_property
in: path
required: true
description: >-
The name of the event property.
schema:
type: string
- name: event_type
in: query
required: true
description: >-
The event type the property belongs to.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EventProperty'
examples:
getEventProperty200Example:
summary: Default getEventProperty 200 response
x-microcks-default: true
value:
event_property: example_value
event_type: standard
description: Example description text
type: standard
is_required: true
'401':
description: Unauthorized
'404':
description: Event property not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateEventProperty
summary: Amplitude Update an Event Property
description: >-
Update an existing event property's metadata.
tags:
- Event Properties
parameters:
- name: event_property
in: path
required: true
description: >-
The name of the event property to update.
schema:
type: string
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- event_type
properties:
event_type:
type: string
description: >-
The event type this property belongs to.
description:
type: string
description: >-
An updated description of the event property.
new_event_property:
type: string
description: >-
A new name for the event property.
type:
type: string
description: >-
The data type of the property.
enum:
- string
- number
- boolean
- enum
- any
is_required:
type: boolean
description: >-
Whether the property is required.
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
updateEventProperty200Example:
summary: Default updateEventProperty 200 response
x-microcks-default: true
value:
success: true
'401':
description: Unauthorized
'404':
description: Event property not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteEventProperty
summary: Amplitude Delete an Event Property
description: >-
Delete a planned event property. This is intended for properties
that have not yet received data.
tags:
- Event Properties
parameters:
- name: event_property
in: path
required: true
description: >-
The name of the event property to delete.
schema:
type: string
- name: event_type
in: query
required: true
description: >-
The event type the property belongs to.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
deleteEventProperty200Example:
summary: Default deleteEventProperty 200 response
x-microcks-default: true
value:
success: true
'401':
description: Unauthorized
'404':
description: Event property not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/taxonomy/user-property:
get:
operationId: listUserProperties
summary: Amplitude List All User Properties
description: >-
Retrieve all user properties in the project. Optionally include
deleted user properties.
tags:
- User Properties
parameters:
- name: showDeleted
in: query
description: >-
When true, include deleted user properties in the response.
schema:
type: boolean
default: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserPropertyListResponse'
examples:
listUserProperties200Example:
summary: Default listUserProperties 200 response
x-microcks-default: true
value:
data:
- example_value
'401':
description: Unauthorized
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createUserProperty
summary: Amplitude Create a User Property
description: >-
Create a new user property in the tracking plan.
tags:
- User Properties
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- user_property
properties:
user_property:
type: string
description: >-
The name of the user property.
description:
type: string
description: >-
A description of the user property.
type:
type: string
description: >-
The data type of the property.
enum:
- string
- number
- boolean
- enum
- any
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
createUserProperty200Example:
summary: Default createUserProperty 200 response
x-microcks-default: true
value:
success: true
'400':
description: Bad request
'401':
description: Unauthorized
'409':
description: User property already exists
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/api/2/taxonomy/user-property/{user_property}:
get:
operationId: getUserProperty
summary: Amplitude Get a User Property
description: >-
Retrieve a single user property by its name.
tags:
- User Properties
parameters:
- name: user_property
in: path
required: true
description: >-
The name of the user property.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserProperty'
examples:
getUserProperty200Example:
summary: Default getUserProperty 200 response
x-microcks-default: true
value:
user_property: example_value
description: Example description text
type: standard
'401':
description: Unauthorized
'404':
description: User property not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateUserProperty
summary: Amplitude Update a User Property
description: >-
Update an existing user property's metadata.
tags:
- User Properties
parameters:
- name: user_property
in: path
required: true
description: >-
The name of the user property to update.
schema:
type: string
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
description:
type: string
description: >-
An updated description of the user property.
new_user_property:
type: string
description: >-
A new name for the user property.
type:
type: string
description: >-
The data type of the property.
enum:
- string
- number
- boolean
- enum
- any
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
updateUserProperty200Example:
summary: Default updateUserProperty 200 response
x-microcks-default: true
value:
success: true
'401':
description: Unauthorized
'404':
description: User property not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteUserProperty
summary: Amplitude Delete a User Property
description: >-
Delete a planned user property. This is intended for properties that
have not yet received data.
tags:
- User Properties
parameters:
- name: user_property
in: path
required: true
description: >-
The name of the user property to delete.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
examples:
deleteUserProperty200Example:
summary: Default deleteUserProperty 200 response
x-microcks-default: true
value:
success: true
'401':
description: Unauthorized
'404':
description: User property 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:
categoryId:
name: category_id
in: path
required: true
description: >-
The ID of the event category.
schema:
type: integer
eventType:
name: event_type
in: path
required: true
description: >-
The name of the event type.
schema:
type: string
schemas:
SuccessResponse:
type: object
properties:
success:
type: boolean
description: >-
Whether the operation was successful.
CategoryListResponse:
type: object
properties:
data:
type: array
description: >-
Array of event categories.
items:
$ref: '#/components/schemas/Category'
Category:
type: object
properties:
id:
type: integer
description: >-
The unique identifier of the category.
name:
type: string
description: >-
The name of the category.
EventTypeListResponse:
type: object
properties:
data:
type: array
description: >-
Array of event types.
items:
$ref: '#/components/schemas/EventType'
EventType:
type: object
properties:
event_type:
type: string
description: >-
The name of the event type.
category:
$ref: '#/components/schemas/Category'
description:
type: string
description: >-
A description of the event type.
EventPropertyListResponse:
type: object
properties:
data:
type: array
description: >-
Array of event properties.
items:
$ref: '#/components/schemas/EventProperty'
EventProperty:
type: object
properties:
event_property:
type: string
description: >-
The name of the event property.
event_type:
type: string
description: >-
The event type this property belongs to.
description:
type: string
description: >-
A description of the event property.
type:
type: string
description: >-
The data type of the property.
is_required:
type: boolean
description: >-
Whether the property is required.
UserPropertyListResponse:
type: object
properties:
data:
type: array
description: >-
Array of user properties.
items:
$ref: '#/components/schemas/UserProperty'
UserProperty:
type: object
properties:
user_property:
type: string
description: >-
The name of the user property.
description:
type: string
description: >-
A description of the user property.
type:
type: string
description: >-
The data type of the property.