Taxonomy API

Updated

Important Note:
This article has been moved to our Developer Center, and will no longer be updated on this site. Here is the newest version of our 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

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

Important Note:

  • You may have to URL encode special characters in the names of event types, event properties, and user properties. For example, 'Play Song' would be 'Play%20Song'. Here is an encoding reference. In addition, note that the examples in this article contain backslash syntax in order to escape characters when using curl. If you are not using curl, then you should not encode your request with backslash escape characters.
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"
      }
   ]
}
Was this article helpful?
1 out of 1 found this helpful
Have more questions? Check out the Amplitude Community.
Return to top