Manage your tracking plans, events, and properties in your data catalog programmatically.
Available Plans
growth
enterprise
35 minute read
The Data Catalog API is a part of RudderStack’s Data Governance toolkit that ensures the quality and integrity of your data in a secure and compliant manner.
You can use the Data Catalog API to:
Create and manage your tracking plans programmatically.
Add or update events and properties in your data catalog.
Create and manage categories for your data catalog events.
Use the base URL for your API requests depending on your region:
https://api.rudderstack.com/v2
https://api.eu.rudderstack.com/v2
Manage tracking plans
This section covers the API endpoints for creating and managing your tracking plans.
Create tracking plan
POST
/catalog/tracking-plans
Request body
name
Required
String
Tracking plan name.
Note that:
The name must be between 3 and 65 characters and should start with a letter.
It must contain only letters, numbers, underscores, commas, spaces, dashes, and dots.
description
Optional
String
Tracking plan description.
Example request
POST/v2/catalog/tracking-plansHTTP/1.1Host:api.rudderstack.comContent-Type:application/jsonAuthorization:Bearer 2glZLfSinoRWdkMqsZYPj48X8dYContent-Length:83{"name":"Product Ordered Plan","description":"Tracking plan for users placing an order for the product."}
curl --location 'https://api.rudderstack.com/v2/catalog/tracking-plans'\
--header 'Content-Type: application/json'\
--header 'Authorization: Bearer 2glZLfSinoRWdkMqsZYPj48X8dY'\
--data '{
"name": "Product Ordered Plan",
"description": "Tracking plan for users placing an order for the product."
}'
Example response
{"id":"tp_5gopz6tfKxAjpS4TjuqVIeTdm7T","name":"Product Ordered Plan","description":"Tracking plan for users placing an order for the product.","version":1,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","creationType":"BackendAPI","createdAt":"2024-05-22T10:34:03.016Z","updatedAt":"2024-05-22T10:34:03.016Z"}
Response codes
Code
Description
200
Tracking plan is successfully created. RudderStack also returns an ID for the newly created tracking plan.
{"trackingPlans":[{"id":"tp_5gopz6tfKxAjpS4TjuqVIeTdm7T","name":"Product Ordered Plan","description":"Tracking plan for users placing an order for the product.","version":1,"createdAt":"2024-05-22T13:07:18.617Z","updatedAt":"2024-05-22T13:07:18.617Z","creationType":"BackendAPI","workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e"},{"id":"tp_2rKxjFu6R1qot19aWhTW7W7Ojew","name":"Order Completed Plan","description":"Tracking plan for users completing an order for the product.","version":4,"createdAt":"2024-01-30T15:41:14.446Z","updatedAt":"2024-02-01T08:59:15.095Z","creationType":"Event Audit API","workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e"}]}
Response codes
Code
Description
200
List of all tracking plans in the associated workspace.
Get tracking plan by ID
GET
/catalog/tracking-plans/{trackingPlanId}
Path parameters
trackingPlanId
Required
String
Tracking plan ID.
version
Optional
String
Tracking plan version. Note that it must be a number.
{"id":"tp_5gopz6tfKxAjpS4TjuqVIeTdm7T","name":"Product Ordered Plan","description":"Tracking plan for users placing an order for the product.","version":1,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","creationType":"BackendAPI","createdAt":"2024-05-22T13:07:18.617Z","updatedAt":"2024-05-22T13:07:18.617Z"}
Response codes
Code
Description
200
Tracking plan is updated successfully.
404
Tracking plan not found for the specified ID.
Update tracking plan
PUT
/catalog/tracking-plans/{trackingPlanId}
Path parameters
trackingPlanId
Required
String
Tracking plan ID.
Request body
To update the tracking plan, at least one of the following parameters is required:
name
String
Tracking plan name.
Note that:
The name must be between 3 and 65 characters and should start with a letter.
It must contain only letters, numbers, underscores, commas, spaces, dashes, and dots.
description
String
Tracking plan description.
Example request
PUT/v2/catalog/tracking-plans/tp_5gopz6tfKxAjpS4TjuqVIeTdm7THTTP/1.1Host:api.rudderstack.comContent-Length:87{
"name": "New Product Ordered Plan",
"description": "Updated tracking plan for users placing an order for the product."
}
curl --location --request PUT 'https://api.rudderstack.com/v2/catalog/tracking-plans/tp_5gopz6tfKxAjpS4TjuqVIeTdm7T'\
--data '{
"name": "New Product Ordered Plan",
"description": "Updated tracking plan for users placing an order for the product."
}'
Example response
{"id":"tp_5gopz6tfKxAjpS4TjuqVIeTdm7T","name":"New Product Ordered Plan","description":"Updated tracking plan for users placing an order for the product.","version":2,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","creationType":"BackendAPI","createdAt":"2024-05-22T10:34:03.016Z","updatedAt":"2024-05-22T10:36:49.252Z"}
Response codes
Code
Description
200
Tracking plan is updated successfully.
400
Bad or invalid request.
Delete tracking plan
Deleted tracking plans cannot be recovered or restored.
{"name":"New Product Ordered Plan","version":1,"description":"Updated tracking plan for users placing an order for the product.","creationType":"BackendAPI","workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","updatedBy":null,"createdAt":"2024-05-22T13:41:33.057Z","updatedAt":"2024-05-22T13:41:33.057Z","events":[]}
Response codes
Code
Description
200
Tracking plan is deleted successfully.
400
Bad or invalid request.
Manage events in tracking plans
This section covers the API endpoints for upserting and managing events in your tracking plans.
The Data Catalog API creates the events and properties in the data catalog only if they do not exist already.
Upsert event to tracking plan
While upserting an event to a tracking plan, make sure the schema of the properties adheres to the advanced rules set for those properties in the data catalog. Otherwise, RudderStack will drop the schema and give the below error:
“Property with name [${prop.name}] and type [${prop.type}] already exists with different advanced keywords.”
If you get this error, you can update the existing catalog property by adding required advanced rules and try again.
PATCH
/catalog/tracking-plans/{trackingPlanId}/events
Path parameters
trackingPlanId
Required
String
Tracking plan ID.
Request body
name
Required
String
Name of the event to be upserted.
Note that:
The name must be between 3 and 65 characters and should start with a letter.
It must contain only letters, numbers, underscores, commas, spaces, dashes, and dots.
For non-track events, the name should be an empty string.
description
Optional
String
Event description.
eventType
Optional
String
Type of event to be upserted.
Note that:
Once set, the event type cannot be updated later.
Allowed event types are track, identify, group, page, and screen.
categoryId
Optional
String
Category ID of the event. It should be a valid, non-empty string.
rules
Required
Object
JSON schema against which RudderStack validates the event. The event rules cannot be empty.
Note: The keywords defined for a property in the rules parameter are the same as the advanced rules defined for a property in the dashboard.
PATCH/v2/catalog/tracking-plans/tp_5gopz6tfKxAjpS4TjuqVIeTdm7T/eventsHTTP/1.1Host:api.rudderstack.comContent-Type:application/jsonAuthorization:••••••Content-Length:955{"name":"Product Viewed","eventType":"track","description":"User viewed a product.","categoryId":null,"rules":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"properties":{"type":"object","required":["amount"],"additionalProperties":false,"properties":{"amount":{"type":["number"]},}}}}}
{"data":[{"id":"ev_2gotMKGuOtdDY4XbSdKjkwk4qc2","name":"Product Viewed","description":"User viewed a product.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","updatedBy":null,"createdAt":"2024-05-22T11:01:24.706Z","updatedAt":"2024-05-22T11:01:24.706Z","identitySection":"properties","additionalProperties":true,}],"total":1,"currentPage":1,"pageSize":50}
Response codes
Code
Description
200
All the events in the tracking plan are fetched successfully.
{"id":"ev_2gotMKGuOtdDY4XbSdKjkwk4qc2","name":"Product Viewed","description":"User viewed a product.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","updatedBy":null,"createdAt":"2024-05-22T11:01:24.706Z","updatedAt":"2024-05-22T11:01:24.706Z","identitySection":"properties","rules":{"$schema":"http://json-schema.org/draft-07/schema#","type":"object","properties":{"properties":{"type":"object","required":["amount"],"additionalProperties":false,"properties":{"amount":{"type":["number"]},}}}}}
Response codes
Code
Description
200
Event specified by the ID is fetched successfully.
404
Tracking plan event not found for the specified ID.
{"name":"Product Viewed","description":"User viewed a product.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","id":"ev_2gqmsfib1Zl6n6QL0mjCi9PJbDS","createdAt":"2024-05-23T03:08:09.972Z","updatedAt":"2024-05-23T03:08:09.972Z"}
Response codes
Code
Description
200
Event is created successfully.
400
Invalid request.
List all events
GET
/catalog/events
Query parameters
orderBy
Optional
String
Order the events list by a specific field.
Allowed fields are name, createdAt, updatedAt. For example, name:asc.
page
Optional
Number
In a paginated view, all the response entries are divided into pages. Use this field to specify which page of results to return. Default value is 1.
{"data":[{"id":"ev_2g60ZQeit5D54rBHUUh0oK3IxzH","name":"Order Placed","description":"User placed an order.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"1zirfVbEQN0zIImR235a1JivVYU","updatedBy":null,"createdAt":"2024-05-06T13:39:34.294Z","updatedAt":"2024-05-06T13:39:34.294Z"},....{"id":"ev_2dJfRK8t0hOmmAaCTc0VvMB36e1","name":"Product Added to Cart","description":"User added product to cart.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"1zirfVbEQN0zIImR235a1JivVYU","updatedBy":"1zirfVbEQN0zIImR235a1JivVYU","createdAt":"2024-03-06T13:18:12.044Z","updatedAt":"2024-05-13T11:39:40.115Z"},],"total":3563,"currentPage":1,"pageSize":50}
Response codes
Code
Description
200
All events in the data catalog are retrieved successfully.
{"id":"ev_2dJfRQIZLrBhqdLoLoxywHpicLp","name":"Product Viewed","description":"User viewed a product.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"1zirfVbEQN0zIImR235a1JivVYU","updatedBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","createdAt":"2024-03-06T13:18:12.044Z","updatedAt":"2024-05-22T14:57:50.265Z","category":null}
Response codes
Code
Description
200
All events in the data catalog are retrieved successfully.
404
Event not found for the specified event ID.
Update event
PUT
/catalog/events/{eventId}
Path parameters
eventId
Required
String
The event ID.
Request body
To update an event in the data catalog, at least one of the following parameters is required:
name
String
Name of the event.
Note that:
The name must be between 3 and 65 characters and should start with a letter.
It must contain only letters, numbers, underscores, commas, spaces, dashes, and dots.
For non-track events, the name should be an empty string.
description
String
Event description.
categoryId
String
Category ID of the event. It should be a valid, non-empty string.
Example request
PUT/v2/catalog/events/ev_2dJfRQIZLrBhqdLoLoxywHpicLpHTTP/1.1Host:api.rudderstack.comContent-Type:application/jsonAuthorization:Bearer 2glZLfSinoRWdkMqsZYPj48X8dYContent-Length:98{"name":"Product Viewed Again","description":"User viewed a product again.","categoryId":null}
{"name":"Product Viewed Again","description":"User revisited a product on the website.","categoryId":null}
Response codes
Code
Description
200
Event is updated successfully.
404
Event not found for the specified event ID.
Delete event
You cannot delete an event that is connected to a tracking plan. Use the Delete event from tracking plan API to disconnect the event and then try deleting it.
{"name":"Product Purchased","description":"User purchased a product on the website.","eventType":"track","categoryId":null,"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","updatedBy":null,"createdAt":"2024-05-22T14:59:14.287Z","updatedAt":"2024-05-22T14:59:14.287Z"}
Response codes
Code
Description
200
Event is deleted from the catalog successfully.
404
Event not found for the specified event ID.
Manage properties in data catalog
This section covers the API endpoints for creating and managing properties in your data catalog.
Create new property
POST
/catalog/properties
Request body
name
Required
String
Property name.
Note that:
The name must be of at least one character and should start with a letter.
It must contain only letters, numbers, underscores, and spaces.
description
Optional
String
Property description.
type
Required
String
Data type of the property.
Note that:
The data type must be either string, integer, number, object, array, boolean, null, or multi data type.
If not explicitly set, RudderStack allows all the above data types for the property, by default.
propConfig
Optional
Object
Advanced rules for the property. See JSON Schema for the complete list of supported keywords.
RudderStack supports multi data type for the type parameter. An example is shown:
{"type":["string","integer","boolean","null"]}
Example request
POST/v2/catalog/propertiesHTTP/1.1Host:api.rudderstack.comContent-Type:application/jsonAuthorization:Bearer 2glZLfSinoRWdkMqsZYPj48X8dYContent-Length:117{"name":"amount","description":"Amount for the product","type":"number","propConfig":{"multipleOf":2},}
{"name":"amount","description":"Amount for the product","type":"number","propConfig":{"multipleOf":2},"workspaceId":"1hitizAoFT91DD6rfFhBjiTex3e","createdBy":"2KDKycoVHAOLttVvzBiqw12O3Hr","id":"prop_2gqpkKg1GtHWKR8JtNChoKsqhIK","createdAt":"2024-05-23T03:31:43.297Z","updatedAt":"2024-05-23T03:31:43.297Z"}
Response codes
Code
Description
200
Property is created successfully.
400
Invalid request.
List all properties
GET
/catalog/properties
Path parameters
orderBy
Optional
String
Order the properties list by a specific field.
Allowed fields are name, createdAt, updatedAt. For example, name:asc.
page
Optional
Number
In a paginated view, all the response entries are divided into pages. Use this field to specify which page of results to return. Default value is 1.
Property is deleted from the catalog successfully.
400
Property not found for the specified event ID.
Manage categories in data catalog
This section covers the API endpoints for creating and managing categories in your data catalog. Go to Govern > Data Catalog > Events tab in your RudderStack dashboard to view the categories and associate them to your events.
Create new category
POST
/catalog/categories
Request body
name
Required
String
Category name.
Note that:
The name must be between 3 and 65 characters and should start with a letter.
It must contain only letters, numbers, underscores, commas, spaces, dashes, and dots.
The request body must not be empty. Otherwise, you will encounter an error.
config
Required
Object
Tracking plan configuration for the source. See Config object structure below for more information.
Config object structure
The config object provided in the request body contains the source-specific tracking plan settings for validating the individual events. A sample object is shown below:
{"config":{"page":{"unplannedProperties":"forward",// or "drop"
"anyOtherViolation":"forward",// or "drop"
"propagateValidationErrors":"true",// or "false"
},"group":{"unplannedProperties":"forward","anyOtherViolation":"forward","propagateValidationErrors":"true"},"track":{"allowUnplannedEvents":"true","unplannedProperties":"forward","anyOtherViolation":"forward","propagateValidationErrors":"true",// or "false"
},"global":{"allowUnplannedEvents":"true","unplannedProperties":"forward","anyOtherViolation":"forward","propagateValidationErrors":"true"},"screen":{"unplannedProperties":"forward","anyOtherViolation":"forward","propagateValidationErrors":"true"},"identify":{"unplannedProperties":"forward","anyOtherViolation":"forward","propagateValidationErrors":"true"}}}
The event-level settings that you can define within the config object are described below. See Source-specific tracking plan settings for more information:
Field
Description
allowUnplannedEvents
Applicable for track object only.
Boolean that determines if RudderStack should drop all events that do not match the predefined event names in the tracking plan.
unplannedProperties
Acceptable values are forward and drop.
Determines if RudderStack should forward or drop events that contain properties not matching the list of predefined properties for the specific event.
anyOtherViolation
Acceptable values are forward and drop.
Determines if RudderStack should forward or drop events with any other violations that include Type Mismatch, Required Fields Missing, and others outlined in the Violation types section.
propagateValidationErrors
Boolean that determines if RudderStack should capture the validation errors in the event’s context object and send them downstream (user transformations and destinations).
Note that:
You need not provide the tracking plan settings for all events. For example, you can include only the track and global objects within config. However, note that you must not provide a blank event object. If included, you must define at least one setting for that event.
RudderStack uses the default settings for the events that you do not specify explicitly and validates them accordingly.
The request body must not be empty. Otherwise, you will encounter an error.
config
Required
Object
Tracking plan configuration for the source. See Config object structure below for more information.
Config object structure
The config object provided in the request body contains the source-specific tracking plan settings for validating the individual events. A sample object is shown below:
The event-level settings that you can define within the config object are described below. See Source-specific tracking plan settings for more information:
Field
Description
allowUnplannedEvents
Applicable for track object only.
Boolean that determines if RudderStack should drop all events that do not match the predefined event names in the tracking plan.
unplannedProperties
Acceptable values are forward and drop.
Determines if RudderStack should forward or drop events that contain properties not matching the list of predefined properties for the specific event.
anyOtherViolation
Acceptable values are forward and drop.
Determines if RudderStack should forward or drop events with any other violations that include Type Mismatch, Required Fields Missing, and others outlined in the Violation types section.
propagateValidationErrors
Boolean that determines if RudderStack should capture the validation errors in the event’s context object and send them downstream (user transformations and destinations).
Note that:
You need not provide the tracking plan settings for all events. For example, you can include only the track and global objects within config. However, note that you must not provide a blank event object. If included, you must define at least one setting for that event.
RudderStack uses the default settings for the events that you do not specify explicitly and validates them accordingly.
Source disconnected from tracking plan successfully.
400
Source already disconnected from tracking plan.
Invalid source ID.
Custom types
Th endpoints covered in this section are in beta as part of RudderStack’s Early Access Program, where we work with early users and customers to test new features and get feedback.
Note that these features are functional but can change as we improve them. Contact the RudderStack team to get access.
This section covers the API endpoints for creating and managing custom types.
Create custom type
POST
/catalog/custom-types
Request body
The request body must not be empty. Otherwise, you will encounter an error.
name
Required
String
Custom type name.
Note that:
The custom type name must be between 2 and 65 characters long.
it must start with a capital letter and contain only letters, numbers, underscores and dashes.
You cannot change the custom type name later.
description
Optional
String
Custom type description.
type
Required
String
Valid data type. Acceptable values are string, number, integer, boolean, null, array, and object.
config
Required
Object
Custom type configuration. See Config object for more details.
properties
Required for object type
Array
Array of properties. See Properties structure for more information on passing this array in the request body.
This parameter is ignored for non-object data types.
Config object
You must include the config object to create a new custom type successfully. You can also pass an empty object to accept any values.
The config object can take the below parameters depending on type (data type of the custom type) specified in the request body:
Custom data type
Acceptable fields
String
Field
Description
enum
Array of acceptable values for the custom type.
minLength
Number defining the minimum string length for the custom type.
maxLength
Number defining the maximum string length for the custom type.
pattern
Regular expression that defining the constraints for the property, for example, email, datetime, URL, ipv4/ipv6, etc.
You can also define a custom pattern.
format
Defines the accepted format.
Acceptable values are datetime, date, time, email, uuid, hostname, ipv4, and ipv6.
Number / Integer
Field
Description
enum
Array of acceptable values for the custom type.
minimum
Minimum acceptable value for the custom type.
maximum
Minimum acceptable value for the custom type.
exclusiveMinimum
Minimum exclusive value for the custom type.
exclusiveMaximum
Maximum exclusive value for the custom type.
multipleOf
Number that is a multiple of a factor.
Array
Field
Description
itemTypes
List of valid data types (including custom type).
If you specify a custom type, note that:
You can include only one custom type, for example, itemTypes: ["CustomType1"].
You cannot include multiple custom types, for example, itemTypes: ["CustomType1", "CustomType2"].
Properties structure
You must include the properties array if your custom type is of the object data type. Note that the properties array must contain a list of objects, with each object containing the following details:
Parameter
Description
id Required
Property ID.
required
Boolean that determines if the property is required or optional.
A sample properties array is shown below:
"properties":[{"id":"prop_<id1>",// Property ID
"required":true/false// Determines whether the property is required or optional
},....{"id":"prop_<id2>","required":true/false}]
The request body must not be empty. Otherwise, you will encounter an error.
config
Required
Object
Updated configuration for the custom type. See Config object for more details.
type
Required
String
New data type for the custom type. Acceptable values are string, number, integer, boolean, null, array, and object.
properties
Required for object type
Array
Array of properties. See Properties structure for more information on passing this array in the request body.
Note: This parameter is ignored for non-object data types.
Config object
You must include the config object to create a new custom type successfully. You can also pass an empty object to accept any values.
The config object can take the below parameters depending on type (data type of the custom type) specified in the request body:
Custom data type
Acceptable fields
String
Field
Description
enum
Array of acceptable values for the custom type.
minLength
Number defining the minimum string length for the custom type.
maxLength
Number defining the maximum string length for the custom type.
pattern
Regular expression that defining the constraints for the property, for example, email, datetime, URL, ipv4/ipv6, etc.
You can also define a custom pattern.
format
Defines the accepted format.
Acceptable values are datetime, date, time, email, uuid, hostname, ipv4, and ipv6.
Number / Integer
Field
Description
enum
Array of acceptable values for the custom type.
minimum
Minimum acceptable value for the custom type.
maximum
Minimum acceptable value for the custom type.
exclusiveMinimum
Minimum exclusive value for the custom type.
exclusiveMaximum
Maximum exclusive value for the custom type.
multipleOf
Number that is a multiple of a factor.
Array
Field
Description
itemTypes
List of valid data types (including custom type).
If you specify a custom type, note that:
You can include only one custom type, for example, itemTypes: ["CustomType1"].
You cannot include multiple custom types, for example, itemTypes: ["CustomType1", "CustomType2"].
Properties structure
You must include the properties array if your custom type is of the object data type. Note that the properties array must contain a list of objects, with each object containing the following details:
Parameter
Description
id Required
Property ID.
required
Boolean that determines if the property is required or optional.
A sample properties array is shown below:
"properties":[{"id":"prop_<id1>",// Property ID
"required":true/false// Determines whether the property is required or optional
},....{"id":"prop_<id2>","required":true/false}]
Step 3: Create a new property of custom array type
Create a new property and set the data type to the custom array type created in the above step. The request body looks as follows:
{"name":"NewPropertyOS",// Replace with the desired name
"description":"Sample property of array custom type","type":"CustomTypeArray","propConfig":{}}
The corresponding request and response looks as follows:
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.
