The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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 Govern add-on (fka Taxonomy add-on).

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

Information About All 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.

Method(s)TypeEndpoint
GETEvent Categoryhttps://amplitude.com/api/2/taxonomy/category/<category_name>
PUT, DELETEEvent Categoryhttps://amplitude.com/api/2/taxonomy/category/<category_id>
GET, POSTEvent Categoryhttps://amplitude.com/api/2/taxonomy/category
GET, PUT, DELETEEvent Typehttps://amplitude.com/api/2/taxonomy/event/<event_type>
GET, POSTEvent Typehttps://amplitude.com/api/2/taxonomy/event
GET, PUT, DELETEEvent Propertyhttps://amplitude.com/api/2/taxonomy/event-property/<event_property>
GET, POSTEvent Propertyhttps://amplitude.com/api/2/taxonomy/event-property
GET, PUT, DELETEUser Propertyhttps://amplitude.com/api/2/taxonomy/user-property/<user_property>
GET, POSTUser Propertyhttps://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 CodeDescription
200Request successful.
400Request is malformed.
404Not found.
429Too many requests for a secret key.
513Server 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

ParameterTypeDescription
category_name (required)stringName of the category. This is the only required parameter for the call.

Example Request

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

Example Responses

{
    "success" : true 
}

Or

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

Get an Event Category

ParameterTypeDescription
category_name (required)stringName of the category. This is the only required parameter for the call.

Example Request

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

Example Responses

{
   "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.

Example Request

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

Example Responses

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

Or

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

Update an Event Category

ParameterTypeDescription
category_id (required)integerID of an existing category. ID can be found with a GET call above.
category_name (required)stringNew name of the category.

Example Request

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

Example Response

{
   {
    "success" : true 
}

Or

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

Delete an Event Category

ParameterTypeDescription
category_id (required)integerID of an existing category. ID can be found with a GET call above.

Example Request

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

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

ParameterTypeDescription
event_type (required)stringName of the event type.
category (optional)stringName of the event type's category.
description (optional)stringAdditional details you would like to add to the event type.

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'

Example Response

{
    "success" : true 
}

Or

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

Get an Event Type

ParameterTypeDescription
event_type (required)stringName of the event type.

Example Request

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

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.

Example Request

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

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

ParameterTypeDescription
event_type (required)stringCurrent name of an existing event type
new_event_type (optional)stringNew name of an event_type.
display_name* (optional)stringDisplay name of an event_type.
category (optional)stringCurrent category name of the event type.
description (optional)stringAdditional details you would like to add to the event type.

*Note: You can only update the display name for an event type that has already been ingested into Amplitude

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 'display_name=Event number 1' --data-urlencode 'new_event_type=new_add_events'

Example Response

{
    "success" : true 
}

Or

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

Delete an Event Type

ParameterTypeDescription
event_type (required)stringName of the planned event type that needs to be deleted.

Example Request

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

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

ParameterTypeDescription
event_type (required)stringName of the event associated with the event property.
event_property (required)stringName you would like to give your event property.
description (optional)stringAdditional details you would like to add to the event property.
type (optional)stringData type of the event property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'
regex (optional)stringRegular 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)listList of allowed values.
is_array_type (optional)booleanTrue 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.

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'

Example Response

{
    "success" : true 
}

Or

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

Get an Event Property

ParameterTypeDescription
event_type (required)stringName of the event type to which the event property belongs to.
event_propertystringName you would like to give your event property.

*Note: event_property is a path parameter while the rest of the parameters are part of the query params. In the example request below user is the event_property we want to GET

Example Request

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

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.

ParameterTypeDescription
event_type (required)stringName of the event type to which the event properties belong to.

Example Request

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

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

ParameterTypeDescription
event_type (required)stringName of the associated event type.
event_property (required)stringExisting name of the event property that needs to be updated.
new_event_property_value (optional)stringNew name of the event property.
description (optional)stringAdditional details you would like to add to the event property type.
type (optional)stringData type of the event property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'.
regex (optional)stringRegular 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)stringList of allowed values, separated by comma (eg: red, yellow, blue).
is_array_type (optional)stringSpecifies whether or not property value is an array. Allowable values are 'true' and 'false'.
is_required (optional)stringAllowable values are 'true' and 'false'. If set to true, event types missing this property will be flagged on their Taxonomy page.

*Note: event_property is a path parameter while the rest of the parameters are part of the query params. In the example request below user is the event_property we want to UPDATE

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'

Example Response

{
    "success" : true 
}

Or

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

Delete an Event Property

ParameterTypeDescription
event_type (required)stringThe event type which the event property belongs to.
event_property (required)stringThe name of the event property that needs to be deleted.

*Note: event_property is a path parameter while the rest of the parameters are part of the query params. In the example request below user is the event_property we want to DELETE

Example Request

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

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

ParameterTypeDescription
user_property (required)stringName of the user property.
description (optional)stringAdditional details you would like to add to the user property.
type (optional)stringData type of the user property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'
regex (optional)stringRegular 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)stringList of allowed values, separated by comma (eg: red, yellow, blue).
is_array_type (optional)stringSpecifies whether or not property value is an array. Allowable values are 'true' and 'false'.

Example Request

curl -u API_Key:Secret_Key -X POST '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'

Example Response

{
    "success" : true 
}

Or

{
    "success" : false 
}

Get a User Property

ParameterTypeDescription
user_property (required)stringName of the user property. The only required parameter of this request.

Example Request

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

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.

Example Request

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

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

ParameterTypeDescription
user_property (required)stringName of the existing user property type.
new_user_property_value (optional)stringNew name of the user property type.
description (optional)stringAdditional details you would like to add to the user property type.
type (optional)stringData type of the user property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'
regex (optional)stringRegular 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)stringList of allowed values, separated by comma (eg: red, yellow, blue).
is_array_type (optional)stringSpecifies whether or not property value is an array. Allowable values are 'true' and 'false'.

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'

Example Request

 {
    "success" : true 
}

Or

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

Delete a User Property

ParameterTypeDescription
user_property (required)stringName of the user property type that needs to be deleted.

Example Request

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

Example Response

{
   "success" : true
}

Or

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

Updated 7 days ago


Taxonomy API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.