API Specification to manage your RudderStack Transformations and Libraries.
14 minute read
RudderStack’s Transformations API allows you to create, read, update and delete transformations and libraries programmatically by making HTTP calls.
This guide describes the various API operations, related request and response structures, and error codes associated with this API.
Basic Authentication
The Transformations API is authenticated via HTTP Basic Authentication.
You can authenticate your account when using the API by including your email address in the username field and the secret access token in the password field in Authorization, if you’re using Postman.
Use the base URL for your API requests depending on your region:
https://api.rudderstack.com
https://api.eu.rudderstack.com
Transformations
RudderStack transformations are responsible for converting received event data into a suitable destination-specific format. All the transformation code is written in JavaScript.
Transformations help you to create a user-defined code that allow you to route your events in a manner that is suitable for your destinations.
Transformer payload
Field
Type
Presence
Description
name
String
Required
Sets the transformation name.
language
String
Required
Language of the transformation code. Acceptable values are javascript and pythonfaas.
description
String
Optional
Sets the transformation description.
code
String
Optional
User-defined code that maps event data to destinations as defined by the user
codeVersion
String
Optional
This is a number value always set to version “1” for API calls.
createdAt
Date
Optional
The timestamp of the transformer when it is created
updatedAt
Date
Optional
The timestamp of the transformer when it is updated
versionId
String
Optional
Maintains a version of transformer every time it is updated
workspaceId
Object
Optional
Workspace ID on which this transformation is created
destinations
Array
Optional
List of all Destination IDs to which your transformation is connected
Create a transformation
Create an unpublished transformation.
When you create a tranfsormation but do not publish it, that is, when publish = false, RudderStack creates revisions for the transformation, but it is not available to incoming event traffic and cannot connect to destinations.
If true, publishes your transformer to the latest version; code is made live for incoming traffic.
Example request:
In this example, publish is false, which is the default setting for the parameter. When unpublished, RudderStack only creates revisions for the transformation, meaning that you cannot connect destinations to the transformation and it cannot be used for incoming event traffic.
POST/transformationsHTTP/1.1Host:api.rudderstack.comAuthorization:Basic YWxleEBleGFtcGxlLmNvbToyTWxxbW9rRGxTeFE2bWJYQ1ZqcVFmbUpoRXk=Content-Type:application/json{"name":"Get metdata","description":"Gets the metadata for an event","code":"export function transformEvent(message, metadata) { const met = metadata(message); return met; }","language":"javascript"}
curl --location 'https://api.rudderstack.com/transformations'\
--header 'Authorization: Basic YWxleEBleGFtcGxlLmNvbToyTWxxbW9rRGxTeFE2bWJYQ1ZqcVFmbUpoRXk='\
--header 'Content-Type: application/json'\
--data '{"name": "Get metdata",
"description": "Gets the metadata for an event",
"code" : "export function transformEvent(event, metadata) { const meta = metadata(event);\n event.meta = meta;\n return event; }",
"language": "javascript"}
Request body:
events
optional
object
Pass a set of JSON events to be tested for your code. This should be an array of JSON data.
destinationIds
optional
array
Pass an array of destinationIds that you wish to connect with this transformation. You can connect only if publish is set to true.
name
optional
string
The transformation name.
description
optional
string
Description of the transformation you are creating.
code
optional
string
The transformation code.
language
required
string
Language of the transformation code. Acceptable values are javascript and pythonfaas.
Example response:
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"2LnbcGgKON5BbHHuyYVesZ24uqu","versionId":"2LnbcImcBqOTkm4FFVCpIakptZJ","name":"Get metdata","description":"Gets the metadata for an event","code":"export function transformEvent(message, metadata) { const met = metadata(message); return met; }","codeVersion":"1","language":"javascript","createdAt":"2023-02-16T01:11:11.586Z","updatedAt":"2023-02-16T01:11:11.586Z"}
Events JSON: When passing events in the request body, format the events in JSON
Publish your transformation. This request is the same as Create transformation except that you need to include ?publish=true in the query, which will allow you to connect destinations to the transformation and make it available to incoming traffic.
When you publish a transformation, we maintain two copies of the transformer: one is published and the other is used for revisions. The published version can be connected to destinations and its code is made live for incoming traffic.
POST
/transformations?publish=true
Query parameters:
publish
optional, default is false
boolean
If true, publishes your transformer to the latest version; code is made live for incoming traffic.
Request body:
events
optional
object
Pass a set of JSON events to be tested for your code. This should be an array of JSON data.
destinationIds
optional
array
Pass an array of destinationIds that you wish to connect with this transformation. You can connect only if publish is set to true.
name
optional
string
Name of the transformer that you wish to create.
description
optional
string
Description of the transformer you are creating.
code
optional
string
The transformer code.
language
required
string
Language of the transformation code. Acceptable values are javascript and pythonfaas.
POST/transformations?publish=trueHTTP/1.1Host:api.rudderstack.comAuthorization:Basic YWxleEBleGFtcGxlLmNvbToyTWxxbW9rRGxTeFE2bWJYQ1ZqcVFmbUpoRXk=Content-Type:application/json{"name":"Cool transformation","description":"A test description","code":"export function transformEvent(event) { return event; }","destinations":["2C8YtptB4KF2eL3KRi9mCFkY3BF"],"language":"javascript"}
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"swderftgy","versionId":"edftgyhu","name":"new Transformations-2","description":"","code":"export function transformEvent(event) { return event; } ","codeVersion":"1","language":"javascript","createdAt":"2021-03-04T04:48:27.288Z","updatedAt":"2021-03-04T04:48:27.288Z","destinations":[]}
Update a transformation
Updating a transformation creates a new revision and sets it as published if the publish flag is set is true, and its code becomes live for upcoming traffic. If the publish flag is false , it only creates a new revision for that transformation.
You cannot update the language used to write the transformation code, that is, a JavaScript transformation cannot be converted to Python and vice versa.
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"1pHw1RmzAqKpRCNupzHjTGfTrPJ","versionId":"1pIfjTI5cOMnSgutkXjTRldt1n3","name":"new Transformations-2","description":"Hey I am updated","code":"export default function cube(x) { return x * x ; }","codeVersion":"1","language":"javascript","createdAt":"2021-03-04T04:48:27.288Z","updatedAt":"2021-03-04T04:48:27.288Z"}
Delete a transformation
Delete a published transformation by ID. Note that RudderStack never deletes a transformation revision.
Gets the number of objects in your array. By default always returns the first 5 objects.
orderBy
optional, default is asc
Pass either asc for ascending or desc for descending. By default, it sets the order as ascending on createdAt.
Possible Values: asc, desc
Example response:
{"TransformationVersions":[{"id":"1pIYoILGZTNYZP4YYkeyNIKlitl","versionId":"1pIYoLfEzcMK3D3M1ihjqI02wnx","name":"Update Transformations and Publish","description":"","code":"export function transformEvent(event) { return event; }\n","codeVersion":"1","language":"javascript","createdAt":"2021-03-04T10:07:24.562Z","updatedAt":"2021-03-04T10:07:24.562Z"},{"id":"1pIYoILGZTNYZP4YYkeyNIKlitl","versionId":"1pIhxFXd7NR7XDA914rLAn5f7wq","name":"Update Transformations and Publish","description":"Hey I am updated again","code":"export default function cube(x) { return x * x * x ; }","codeVersion":"1","language":"javascript","createdAt":"2021-03-04T11:22:36.102Z","updatedAt":"2021-03-08T04:22:42.646Z"}]}
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"1pIYoILGZTNYZP4YYkeyNIKlitl","versionId":"1pIYoLfEzcMK3D3M1ihjqI02wnx","name":"Update Transformations and Publish","description":"Updated sample transformation ready to be published","code":"export function transformEvent(event) { return event; }\n","codeVersion":"1","language":"javascript","createdAt":"2021-03-04T10:07:24.562Z","updatedAt":"2021-03-04T10:07:24.562Z"}
Libraries
Libraries are JavaScript code that you can write and export to be used in your transformations. They give you the flexibility for reusing and maintaining different versions of the transformation code.
Suppose you write an aggregation function. You can easily export them and use it within different transformations just by importing that module by the library name.
Libraries payload
Field
Type
Presence
Description
name
String
Required
Sets the library name. This name is used as modules when it is imported in the transformation code.
language
String
Required
Language of the library code. Acceptable values are javascript and pythonfaas.
description
String
Optional
Sets the library description
code
String
Optional
The library code.
importName
String
Optional
This is library name that users can use in their transformation code while importing that library.
createdAt
Date
Optional
The timestamp when the transformer is created.
updatedAt
Date
Optional
The timestamp when the transformer is updated.
versionId
String
Optional
Maintains a version of library every time it is updated.
workspace
Object
Optional
Dictionary of information that provides workspace data where any transformation is used.
Create a library
Create a library and get its object as a response.
POST
/libraries
Example request:
POST/librariesHTTP/1.1Host:api.rudderstack.comAuthorization:Basic TVlfRU1BSUxfQUREUkVTUzpNWV9BQ0NFU1NfVE9LRU4=Content-Type:application/jsonContent-Length:164{"name":"cool library","description":"cool description","code":"export function add(a,b) {return a+b; } export function sub(a,b) {return a-b; }","language":"javascript"}
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"libraries":[{"id":"1pHx15j5rXvmmQUIMBaQdIyrpr2","versionId":"1pHxdlGL8IyoP7WfvRil4Qs88cp","name":"Get Cube","description":"First Library using apiCall","code":"export default function cube(x) { return x * x ; }","language":"javascript","createdAt":"2021-03-04T05:01:46.985Z","updatedAt":"2021-03-04T05:01:47.141Z","importName":"getCube"},{"id":"1pT7933tHRBPlEMIZt5Zi3VIht1","versionId":"1pT793mcqQkcyHdqwXkxHmtgMMg","name":"User Defined Library","description":"Get User context","code":" export default function cube(x) { return x * x * x; }","language":"javascript","createdAt":"2021-03-08T03:47:51.512Z","updatedAt":"2021-03-08T03:47:51.512Z","importName":"userDefinedLibrary"}]}
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"1pT7933tHRBPlEMIZt5Zi3VIht1","versionId":"1pT793mcqQkcyHdqwXkxHmtgMMg","name":"User Defined Library","description":"Get User context","code":" export default function cube(x) { return x * x * x; }","language":"javascript","createdAt":"2021-03-08T03:47:51.512Z","updatedAt":"2021-03-08T03:47:51.512Z","importName":"userDefinedLibrary"}
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"libraryVersions":[{"id":"1pT7933tHRBPlEMIZt5Zi3VIht1","versionId":"1pT793mcqQkcyHdqwXkxHmtgMMg","name":"userDefinedLibrary","description":"Get User context","code":"export default function cube(x) { return x * x * x; }","language":"javascript","createdAt":"2021-03-08T03:47:51.686Z","updatedAt":"2021-03-08T03:47:51.686Z","isPublished":false},{"id":"1pT7933tHRBPlEMIZt5Zi3VIht1","versionId":"1pT8KDAD66mQxnaUQxJpNs9qLFn","name":"userDefinedLibrary","description":"Get Divisible by 2","code":"export default function cube(x) { return 2 * x; }","language":"javascript","createdAt":"2021-03-08T03:57:33.738Z","updatedAt":"2021-03-08T03:57:33.738Z","isPublished":true}]}
Query parameters:
count
optional
number
Gets the number of objects in your array. By default always returns the first 5 objects.
orderBy
optional, default is asc
Pass either asc for ascending or desc for descending. By default, it sets the order as ascending on createdAt.
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"1pT7933tHRBPlEMIZt5Zi3VIht1","versionId":"1pT8KDAD66mQxnaUQxJpNs9qLFn","name":"userDefinedLibrary","description":"Get Divisible by 2","code":"export default function cube(x) { return 2 * x; }","language":"javascript","createdAt":"2021-03-08T03:57:33.738Z","updatedAt":"2021-03-08T03:57:33.738Z","isPublished":false}
Update a library
This request lets you update the code and description of the transformation library by specifying its ID. To publish the library, set the publish flag to true. If the publish flag is false , it only creates a new version of that library.
Note that:
You cannot change the name of the library using this request.
You cannot update the language used to write the library code, that is, a JavaScript library cannot be converted to Python and vice versa.
curl --location 'https://api.rudderstack.com/libraries/2MTEP4IhlKLXYtnbOqAOx1kKcBd'\
--data '{
"description": "Updated library code from cube function to a sum function",
"code": "export default function cube(x) { return 2 * x; }",
"language": "javascript"
}'
Example response:
HTTP/1.1200OKcontent-type:application/json; charset=utf-8{"id":"1pHw1RmzAqKpRCNupzHjTGfTrPJ","versionId":"1pIfjTI5cOMnSgutkXjTRldt1n3","name":"new Transformations-2","description":"Hey I am updated","code":"export default function cube(x) { return 2 * x; }","codeVersion":"1","language":"javascript","createdAt":"2021-03-04T04:48:27.288Z","updatedAt":"2021-03-04T04:48:27.288Z"}
As an end user you can create a transformer/library and perform several edits on it. Note that publishing is optional at create.
If you perform some edits on this version of transformer, RudderStack takes your latest update as the published version, creates a copy of the older version, and saves it as revisions. Let’s assume that after creating some 7 to 8 such revisions of your transformer, you finally decide to use the second or third version of the transformer.
This is where the RudderStack Publish API comes into play.
Publish a transformation or library
Publish any transformation revisions or library revisions.
Pass an array of transformer versionIds that you wish to publish.
libraries
optional
array
Pass an array of library versionIds that you wish to publish.
One of above transformations or libraries must be present to make a successful publish call.
A few things to note:
You can choose to publish some revisions transformer without the libraries.
You can choose to publish some revisions libraries without the transformers.
You can publish both library and transformation revisions.
Whenever you call the publish API, we run tests in our server to make sure you won’t save any transformation/libraries code that can lead to any exceptions.
In case if your publish is failing, make sure to check your transformation code and the libraries that it is referring to.
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.