Taxonomy API

 

The Taxonomy API grants Scholarship, Growth, and Enterprise clients the ability to programmatically maintain their event schema in the Taxonomy tab.

Note that some functions are available for all customers on the Scholarship, Growth, and Enterprise plan, while others like edits to the schema, are only available to customers who have purchased the Taxonomy add-on. 

IMPORTANT NOTE: Please read the Request Limits section thoroughly. Exceeding any of these limits will return a 429 error.

Table of Contents

• API Endpoints
• Request Limits
• HTTP Status Codes & Failed Requests
• Event Category
• Create an Event Category
• Get an Event Category
• Get all Event Categories
• Update Event Category
• Delete an Event Category
• Event Type
• Create an Event Type
• Get an Event Type
• Get all Event Types
• Update an Event Type
• Delete an Event Type
• Event Property
• Create an Event Property
• Get an Event Property
• Get all Event Properties
• Update an Event Property
• Delete an Event Property
• User Property
• Create a User Property
• Get a User Property
• Get all User Properties
• Update a User Property
• Delete a User Property

API Endpoints

Authenticate via basic authentication with the credentials API_Key:Secret_Key. Below are the supported endpoints. 

Methods	Endpoints
GET Event Category	https://amplitude.com/api/2/taxonomy/category/<category_name>
PUT|DELETE Event Category	https://amplitude.com/api/2/taxonomy/category/<category_id>
GET|POST Event Category	https://amplitude.com/api/2/taxonomy/category
GET|PUT|DELETE Event Type	https://amplitude.com/api/2/taxonomy/event/<event_type>
GET|POST Event Type	https://amplitude.com/api/2/taxonomy/event
GET|PUT|DELETE Event Property	https://amplitude.com/api/2/taxonomy/event-property/<event_property>
GET|POST Event Property	https://amplitude.com/api/2/taxonomy/event-property
GET|PUT|DELETE User Property	https://amplitude.com/api/2/taxonomy/user-property/<user_property>
GET|POST User Property	https://amplitude.com/api/2/taxonomy/user-property

 

Request Limits

For each endpoint, there is a concurrent and a rate limit. The concurrent limit restricts the amount of requests you can run at the same time, while the rate limit restricts the total number of queries you can run per hour. The limits are per project (i.e. per API Key), and exceeding any of these limits will return a 429 error.

The endpoints take into account a concept of cost per query. Below are the max costs per API Key:

• Concurrent Cost Limit: You can run queries that collectively add up to 4 cost at the same time.
• Period Cost Limit: You can run up to 7200 cost per hour.

Cost structure of each endpoint:

• GET: 1 cost
• PUT: 2 cost
• POST: 2 cost
• DELETE: 2 cost

HTTP Status Codes and Failed Requests

Error Code	Description
200	Request successful.
400	Request is malformed.
404	Not found.
429	Too many requests for a secret key.
513	Server error. A request with this response can be retried without any risk of duplicating an event.

 

Event Category

The following calls will allow you to Create, Get, Update, and Delete event categories.

Create an Event Category

Parameters	Description
category_name (required) string	Name of the category. This is the only required parameter for the call.

Below is an example request:

curl -u API_Key:Secret_Key -X POST 'https://amplitude.com/api/2/taxonomy/category' --data-urlencode 'category_name=category_test'

Below is an example response:

{
    "success" : true 
}

Or 
{
   "success" : false,
   "errors" : [
      {
         "message" : "error info"
      }
   ]

Get an Event Category

Parameters	Description
category_name (required) string	Name of the category. This is the only required parameter for the call.

Below is an example request.

curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/category/category_name'

Below is an example response:

{
   "data" : {
      "name" : "category_test",
      "id" : 4786
   },
   "success" : true
}

Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Get all Event Categories

There are no required parameters for this call. Below is an example request.

curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/category'

Below is an example response:

{
   "success" : true,
   "data" : [
      {
         "name" : "category_test",
         "id" : 4786
      }
   ]
}
Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Update an Event Category

Parameters	Description
category_id (required) integer	ID of an existing category. ID can be found with a GET call above.
category_name (required) string	New name of the category.

Below is an example request.

curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/category/4786'  --data-urlencode 'category_name=category_testNew'

Below is an example response:

{
   {
    "success" : true 
}

Or 
{
   "errors" : [
      {
         "message" : “Not found”
      }
   ],
   "success" : false
}
}

Delete an Event Category

Parameters	Description
category_id (required) integer	ID of an existing category. ID can be found with a GET call above.

Below is an example request.

curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/category/4786' 

Below is an example response:

{
   "success" : true
}

Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Event Type

The following calls will allow you to Create, Get, Update, and Delete event types.

Create an Event Type

Parameters	Description
event_type (required) string	Name of the event type.
category (optional) string	Name of the event type's category.
description (optional) string	Additional details you would like to add to the event type.

Below is an example request.

curl -u API_Key:Secret_Key -X POST 'https://amplitude.com/api/2/taxonomy/event' --data-urlencode 'event_type=add_event' --data-urlencode 'category=category_test' --data-urlencode 'description=add events' 

Below is an example response:

{
    "success" : true 
}

Or 
{
   "errors" : [
      {
         "message" : “some errors info”
      }
   ],
   "success" : false
}

Get an Event Type

Parameters	Description
event_type (required) string	Name of the event type.

Below is an example request.

curl -u API_Key:Secret_Key -X GET ''https://amplitude.com/api/2/taxonomy/event/add_event'

Below is an example response:

{
   "success" : true,
   "data" : {
      "category" : {
         "name" : "category_test"
      },
      "description" : "add events",
      "event_type" : "add_event"
   }
}

Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Get all Event Types

There are no required parameters for this call. Below is an example request.

curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/event'

Below is an example response:

{
	"success": true,
	"data": [{
			"category": {
				"name": "category_test"
			},
			"description": "add events",
			"event_type": "add_event"
		},
		{
			"category": null,
			"event_type": "Visit tab: timelines.detail",
			"description": null
		},
		{
			"description": null,
			"category": null,
			"event_type": "Visit tab: timelines.realtime"
		}
	]
}
Or 
{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Update an Event Type

Parameters	Description
event_type (required) string	Current name of an existing event type
new_event_type (optional) string	New name of an event_type.
category (optional) string	Current category name of the event type.
description (optional) string	Additional details you would like to add to the event type.

Below is an example request.

curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/event/add_event' --data-urlencode 'category=category_test' --data-urlencode 'description=new add events' --data-urlencode ‘new_event_type=new_add_events'

Below is an example response:

{
    "success" : true 
}

Or 
{
   "errors" : [
      {
         "message" : “some errors info”
      }
   ],
   "success" : false
}

Delete an Event Type

Parameters	Description
event_type (required) string	Name of the planned event type that needs to be deleted.

Below is an example request.

curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/event/add_event' 

Below is an example response:

{
   "success" : true
}
Or 
{
   "success" : false,
   "errors" : [
      {
         "message" : "Attempted to remove an event, \"add_event'\", that is not a planned event."
      }
   ]
}

Event Property

The following calls will allow you to Create, Get, Update, and Delete event property types.

Create an Event Property

Parameters	Description
event_type (required) string	Name of the event associated with the event property.
event_property (required) string	Name you would like to give your event property.
description (optional) string	Additional details you would like to add to the event property.
type (optional) string	Data type of the event property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'.
regex (optional) string	Regular expression, custom regex that can be used for pattern matching or more complex values. (e.g. property zip code must have pattern [0-9]{5} )
enum_values (optional) list	List of allowed values.
is_array_type (optional) boolean	True or false values only.
is_required (optional) boolean	True or false values only. If set to `true`, event types missing this property will be flagged on their Taxonomy page.

Below is an example request.

curl -u API_Key:Secret_Key -X POST 'https://amplitude.com/api/2/taxonomy/event-property'  --data-urlencode 'event_type=add_event' --data-urlencode 'event_property=user' --data-urlencode 'description= user id' --data-urlencode 'type=string' --data-urlencode 'regex=[0-9]{5}' --data-urlencode 'is_array_type=false' --data-urlencode 'is_required=false'

Below is an example response:

{
    "success" : true 
}

Or 
{
   "errors" : [
      {
         "message" : “some errors info”
      }
   ],
   "success" : false
}

Get an Event Property

Parameters	Description
event_type (required) string	Name of the event type to which the event property belongs to.
event_property string	Name you would like to give your event property.

Below is an example request.

curl -u API_Key:Secret_Key -X GET ''https://amplitude.com/api/2/taxonomy/event-property/user?event_type=add_event'

Below is an example response:

{
   "data" : {
      "description" : "user id",
      "event_type" : "add_event",
      "event_property" : "user",
       "regex": null,
       "is_required": true,
       "is_array_type": true, 
       "enum_values": null, 
       "type": "string"
   },
   "success" : true
}
Or 
{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Get all Event Properties

This call allows you to retrieve all event property types associated with a specified event type.

Parameters	Description
event_type (required) string	Name of the event type to which the event properties belong to.

Below is an example request.

curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/event-property?event_type=add event'

Below is an example response:

{
   "data" : [
      {
      "description" : "user id",
      "event_type" : "add_event",
      "event_property" : "user",
       "regex": null,
       "is_required": true,
       "is_array_type": true, 
       "enum_values": null, 
       "type": "string"         "event_property" : "user",
         "event_type" : "add_event",
         "description" : "user id"
      }
   ],
   "success" : true
}
           Or 
{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Update an Event Property

Parameters	Description
event_type (required) string	Name of the associated event type.
event_property (required) string	Existing name of the event property that needs to be updated.
new_event_property (optional) string	New name of the event property.
description (optional) string	Additional details you would like to add to the event property type.
type (optional) string	Data type of the event property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'.
regex (optional) string	Regular expression or custom regex that can be used for pattern matching and more complex values (e.g. 'zip code' property must have pattern [0-9]{5} ).
enum_values (optional) string	List of allowed values, separated by comma (eg: red, yellow, blue).
is_array_type (optional) string	Specifies whether or not property value is an array. Allowable values are 'true' and 'false'.
is_required (optional) string	Allowable values are 'true' and 'false'. If set to `true`, event types missing this property will be flagged on their Taxonomy page.

Below is an example request.

curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/event-property/user'  --data-urlencode 'description=user name' --data-urlencode 'event_type=add_event_new' --data-urlencode 'type=string' --data-urlencode 'regex=[0-9]{5}' --data-urlencode 'is_array_type=false' --data-urlencode 'is_required=true-data-urlencode 'new_event_property_value=user_name'

Below is an example response:

{
    "success" : true 
}

Or 
{
   "errors" : [
      {
         "message" : “some errors info”
      }
   ],
   "success" : false
}

Delete an Event Property

Parameters	Description
event_type (required) string	The event type which the event property belongs to.
event_property (required) string	The name of the event property that needs to be deleted.

Below is an example request.

curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/event-property/user?event_type=/add_event' 

Below is an example response:

{
   "success" : true
}

Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

User Property

The following calls will allow you to Create, Get, Update, and Delete user property types.

Create a User Property

Parameters	Description
user_property (required) string	Name of the user property.
description (optional) string	Additional details you would like to add to the user property.
type (optional) string	Data type of the user property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'
regex (optional) string	Regular expression or custom regex that can be used for pattern matching and more complex values (e.g. 'zip code' property must have pattern [0-9]{5} ).
enum_values (optional) string	List of allowed values, separated by comma (eg: red, yellow, blue).
is_array_type (optional) string	Specifies whether or not property value is an array. Allowable values are 'true' and 'false'.

Below is an example request.

curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/user-property'  --data-urlencode 'user_property=age' --data-urlencode 'description=I do not know'  --data-urlencode 'type=string' --data-urlencode 'regex=[0-9]{1,2}' --data-urlencode 'is_array_type=false'

Below is an example response:

{
    "success" : true 
}

Or 
{
    "success" : false 
}

Get a User Property

Parameters	Description
user_property (required) string	Name of the user property. The only required parameter of this request.

Below is an example request.

curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/user-property/age'

Below is an example response:

{
   "data" : {
         "user_property" : "age ",
         "description" :  "how old this user is",
         "regex": null,
         "is_array_type": false, 
         "enum_values": null, 
         "type": "string"  
   },
   "success" : true
}


Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Get all User Properties

There are no required parameters for this call. Below is an example request.

curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/user-property'

Below is an example response:

{
   "success" : true,
   "data" : [
      {
         "user_property" : "age ",
         "description" :  "how old this user is",
         "regex": null,
         "is_array_type": false, 
         "enum_values": null, 
         "type": "string"        
    ]
}
Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}

Update a User Property

Parameters	Description
user_property (required) string	Name of the existing user property type.
new_user_property (optional) string	New name of the user property type.
description (optional) string	Additional details you would like to add to the user property type.
type (optional) string	Data type of the user property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'
regex (optional) string	Regular expression or custom regex that can be used for pattern matching and more complex values (e.g. 'zip code' property must have pattern [0-9]{5} ).
enum_values (optional) string	List of allowed values, separated by comma (eg: red, yellow, blue).
is_array_type (optional) string	Specifies whether or not property value is an array. Allowable values are 'true' and 'false'.

Below is an example request.

curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/user-property/age'  --data-urlencode 'description=first name' --data-urlencode 'new_user_property_value=first_name'  --data-urlencode 'type=string' --data-urlencode 'regex=None' --data-urlencode 'enum_values=None' --data-urlencode 'is_array_type=false'

Below is an example response:

 {
    "success" : true 
}

Or 
{
   "errors" : [
      {
         "message" : “Not found”
      }
   ],
   "success" : false
}

Delete a User Property

Parameters	Description
user_property (required) string	Name of the user property type that needs to be deleted.

Below is an example request.

curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/user-property/age' 

Below is an example response:

{
   "success" : true
}

Or 

{
   "success" : false,
   "errors" : [
      {
         "message" : "Not found"
      }
   ]
}