Transformations API
API Specification to manage your RudderStack Transformations and Libraries.
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.
It is mandatory to generate your access token before you make any API calls. If you have not generated your access token visit our Access Token page.
Any API requests without the authentication will fail.
You can also pass your access token in the authorization headers, as shown:
1
Authorisation: Basic {Base64Encoded(emailaddress:AccessToken)}
Copied!
The basic auth contains three parts:
    Basic
    Base64Encoded (Token)
    Token = emailaddress + colon + access token
Some examples are as shown:
To make a successful request all of the upcoming endpoints should include this header.

Transformations

RudderStack transformations are responsible for converting the received event data into a suitable destination-specific format. All the transformation codes are written in JavaScript.
We also support user-specific transformations for real-time operations, such as aggregation and sampling.
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 name of Transformer
description
String
Optional
Gives a description for a transformer
code
String
Optional
User-defined code that maps event data to destinations as defined by the user
codeVersion
String
Optional
This is an integer data 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
post
https://api.rudderstack.com
/transformations
Create a transformation
Events Parameters : Passing events in our API accepts a JSON format.
1
[
2
{
3
"anonymousId": "8d872292709c6fbe",
4
"channel": "mobile",
5
"context": {
6
"traits": {
7
"address": {
8
"city": "Kolkata",
9
"country": "India",
10
"postalcode": "700096",
11
"state": "West bengal",
12
"street": "Park Street"
13
}
14
}
15
},
16
"properties": {
17
"revenue": "30",
18
"currency": "USD",
19
"quantity": "5",
20
"price": "58.0"
21
}
22
}
23
]
Copied!
Creating a transformation can be done in one of the two ways:
publish: true - In this case, we maintain two copies of the transformer. Among these, one is published and other is used for revisions. With the published version, you can connect a destination and its code is made live for incoming traffic.
publish: false - In this case, we only create revisions for the transformation, which means you cannot connect any destinations to it. It cannot be used for any incoming event traffic. However, if you wish to publish some revisions of transformations you can do so using our Publish API.
We will be using these two terms Published and Revisions for transformations and libraries throughout our docs.
An example is as shown:
Curl
Httpie
1
curl --location -X POST 'https://api.rudderstack.com/transformations' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"name": "Create Transformation Tested-4",
6
"code": "function transformEvent(events) { return events; } ",
7
"description": "Descriptrion 1"
8
}'
Copied!
1
http POST 'https://api.rudderstack.com/transformations' \
2
name='Create Transformation Tested-4' code='function transformEvent(events) { return events; }' description='Descriptrion 1' \
3
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
4
Content-Type:'application/json'
Copied!
get
https://api.rudderstack.com
/transformations
List all the transformations
Curl
Httpie
1
curl --location -X GET 'https://api.rudderstack.com/transformations' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
Copied!
1
http GET 'https://api.rudderstack.com/transformations' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
Copied!
get
https://api.rudderstack.com
/transformations/{id}
Retrieve a single Transformation
Curl
Httpie
1
curl --location -X GET 'https://api.rudderstack.com/transformations/1pSvMXr651E1gWeErQNQlSQU5Bg' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
Copied!
1
http GET 'https://api.rudderstack.com/transformations/1pSvMXr651E1gWeErQNQlSQU5Bg' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
Copied!
post
https://api.rudderstack.com
/transformations/{id}
Update a transformation
An example request is as shown:
Curl
Httpie
1
curl --location -X POST 'https://api.rudderstack.com/transformations/1pSvMXr651E1gWeErQNQlSQU5Bg' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"name": "name updated"
6
}'
Copied!
1
http POST 'https://api.rudderstack.com/transformations/1pSvMXr651E1gWeErQNQlSQU5Bg' \
2
name='name updated'
3
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
4
Content-Type:'application/json'
Copied!
delete
https://api.rudderstack.com
/transformations/{id}
Delete a transformation
Curl
Httpie
1
curl --location -X DELETE 'https://api.rudderstack.com/transformations/1pSvMXr651E1gWeErQNQlSQU5Bg' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
Copied!
1
http DELETE 'https://api.rudderstack.com/transformations/1pSvMXr651E1gWeErQNQlSQU5Bg' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
Copied!
get
https://api.rudderstack.com
/transformations/{id}/versions
List all transformation versions
An example request is as shown:
Curl
Httpie
1
curl --location -X GET 'https://api.rudderstack.com/transformations/1pIYoILGZTNYZP4YYkeyNIKlitl/versions' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
Copied!
1
http GET 'https://api.rudderstack.com/transformations/1pIYoILGZTNYZP4YYkeyNIKlitl/versions' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
Copied!
get
https://api.rudderstack.com
/transformations/{id}/versions/{versionId}
Retrieve a single transformation version
Curl
Httpie
1
curl --location --request GET 'https://api.rudderstack.com/transformations/1pIYoILGZTNYZP4YYkeyNIKlitl/versions/1pIhxFXd7NR7XDA914rLAn5f7wq' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
Copied!
1
http GET 'https://api.rudderstack.com/transformations/1pIYoILGZTNYZP4YYkeyNIKlitl/versions/1pIhxFXd7NR7XDA914rLAn5f7wq' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
Copied!

Libraries

Libraries are JavaScript codes 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 name of Library. This name is used as modules when it is imported in the transformation code.
description
String
Optional
Gives a description for a library.
code
String
Optional
User-defined code.
importName
String
Optional
This is library name that user can use in his 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.
post
https://api.rudderstack.com
/libraries
Create a library
The publish flag for a library works in the same way as for destinations.
Curl
Httpie
1
curl --location -X POST 'https://api.rudderstack.com/libraries' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"name": "User Defined Library",
6
"description": "Get User context",
7
"code": "export default function cube(x) { return x * x * x; }"
8
}'
Copied!
1
http POST 'https://api.rudderstack.com/libraries' \
2
name='User Defined Library' description='Get User context' code='export default function cube(x) { return x * x * x; }' \
3
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
4
Content-Type:'application/json'
Copied!
get
https://api.rudderstack.com
/libraries
List all libraries
Curl
Httpie
1
curl --location -X GET 'https://api.rudderstack.com/libraries' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
Copied!
1
http GET 'https://api.rudderstack.com/libraries' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
3
Content-Type:'application/json'
Copied!
get
https://api.rudderstack.com
/libraries/{id}
Retrieve a library
Curl
Httpie
1
curl --location -X GET 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
Copied!
1
http GET 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
3
Content-Type:'application/json'
Copied!
post
https://api.rudderstack.com
/libraries/{id}
Update a library
Updating a library with publish has same flow as for transformations.
A sample request is as shown:
Curl
Httpie
1
curl --location -X POST 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
4
-d '{
5
"description": "Get Divisible by 2",
6
"code": "export default function cube(x) { return 2 * x; }"
7
}'
Copied!
1
description='Get Divisible by 2' code='export default function cube(x) { return 2 * x; }'
2
http POST 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1' \
3
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
4
Content-Type:'application/json'
Copied!
get
https://api.rudderstack.com
/libraries/{id}/versions
List all library versions.
Curl
Httpie
1
curl --location --request GET 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1/versions' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
Copied!
1
http GET 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1/versions' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
3
Content-Type:'application/json'
Copied!
get
https://api.rudderstack.com
/libraries/{id}/versions/{versionId}
Retrieve a single library versions
Curl
Httpie
1
curl --location -X GET 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1/versions/1pT8KDAD66mQxnaUQxJpNs9qLFn' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
Copied!
1
http GET 'https://api.rudderstack.com/libraries/1pT7933tHRBPlEMIZt5Zi3VIht1/versions/1pT8KDAD66mQxnaUQxJpNs9qLFn' \
2
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
3
Content-Type:'application/json'
Copied!

Publish the API

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 Payload:

Field
Type
Presence
Description
transformations
Array
Optional
Pass an array of transformer versionIds that you wish to publish.
libraries
Array
Optional
Pass an array of library versionIds you wish to publish.
Any one of above payload must be present to make a successful publish call.
post
https://api.rudderstack.com
/transformations/libraries/publish
Publish a transformation or library
The sample request is as shown:
1
Request Payload ::
2
{
3
transformations: [
4
{
5
versionId: publishTransformerVersionId,
6
testInput:
7
'[
8
{
9
"anonymousId":"8d872292709c6fbe",
10
"channel":"mobile"
11
},
12
{
13
"anonymousId":"8d872292709c6fbe",
14
"channel":"mobile"
15
}
16
],
17
libraries: [
18
{
19
versionId: publishLibraryVersionId1,
20
},
21
{
22
versionId: publishLibraryVersionId1,
23
}
24
]
25
}
Copied!
Curl
Httpie
1
curl --location -X POST 'https://api.rudderstack.com/transformations/libraries/publish' \
2
-H 'Authorization: Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN) \
3
-H 'Content-Type: application/json' \
4
-d '{
5
transformations: [
6
{
7
versionId: publishTransformerVersionId,
8
testInput:
9
'[
10
{
11
"anonymousId":"8d872292709c6fbe",
12
"channel":"mobile"
13
},
14
{
15
"anonymousId":"8d872292709c6fbe",
16
"channel":"mobile"
17
}
18
],
19
libraries: [
20
{
21
versionId: publishLibraryVersionId1,
22
},
23
{
24
versionId: publishLibraryVersionId1,
25
}
26
]
27
}'
Copied!
1
http POST 'https://api.rudderstack.com/transformations/libraries/publish' \
2
transformations='[{versionId: publishTransformerVersionId, testInput:'[{"anonymousId":"8d872292709c6fbe","channel":"mobile"},{"anonymousId":"8d872292709c6fbe","channel":"mobile"}] libraries='[{versionId: publishLibraryVersionId1,},{versionId: publishLibraryVersionId1}]' \
3
Authorization: 'Basic Base64Enc(EMAIL_ADDRESS:ACCESS_TOKEN)' \
4
Content-Type:'application/json'
Copied!
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.

Contact Us

To know more about the Transformations API, please feel free to contact us. You can also start a conversation on our Slack channel, and we will be happy to help you.
Last modified 2mo ago