HTTP API
Detailed technical description of the RudderStack HTTP API for sending your event data from your sources to the specified destinations.
We recommend using the RudderStack SDKs for tracking and routing user events from your sources. The SDKs also offer automatic tagging of user context, event batching, and a retry functionality during delivery failure.
RudderStack offers an easy-to-use HTTP API that you can use to send your events if you cannot use the SDKs.
The RudderStack HTTP API is fully Segment-compatible.
This document details various aspects of the HTTP API.
1. Prerequisites
The following prerequisites must be met to send events via the HTTP API:
The RudderStack HTTP server must be accessible from your HTTP client. Refer to this guide to install and set up RudderStack in your preferred environment.
Set up a source and destination in RudderStack by following the steps from Adding a Source and Adding a Destination guides.
Import the Postman collection using using this URL and edit the variables
source_write_key
anddata_plane_url
with the source write key and the Data Plane URL.
If you are using RudderStack Cloud, set the Data Plane URL to https://hosted.rudderlabs.com
.
2. API Authorization
RudderStack uses Basic Authentication for authenticating all the HTTP requests.
All the popular HTTP clients (e.g. CURL, Postman, HTTPie) have default support for Basic Authentication.
The Basic Authentication for this API requires a username and password where:
The username is the source write key
The password is an empty string (
""
)
For example, if the source write key is 1Xk5DChfJAol3xtW7qNnK1apo5p
, your HTTP request must have the following HTTP header Authorization: Basic MVhrNURDaGZKQW9sM3h0VzdxTm5LMWFwbzVwOg==
You can use this Basic Authentication Header Generator to generate the HTTP header.
Important: To send the events via the RudderStack HTTP API, the Content-Type header must be set to application/json
.
3. HTTP Responses
The HTTP API returns a
200
response for successful API requests.The API returns a
400
response for invalid requests with an appropriate error message in the response. Some possible invalid requests include:Request size too large
Invalid JSON
Missing Authorization Header
Invalid Authorization Header
In case of the Invalid Authorization Header error, verify if the source write key and the Basic Auth Header is valid.
4. Maximum Allowed Request Size
RudderStack allows messages with a maximum size of 32 KB
per call. The batch
endpoint accepts a maximum call size of 4 MB
per batch, and 32 KB
per call. RudderStack responds with a 400 Bad Request
if these limits are exceeded.
5. Identify
The identify
call lets you associate a visiting user to their actions and record any associated traits.
Request Type: POST
Request Format**:**
5.1. Sample Payload
5.2. Usage
CURL HTTPie
5.3. Accepted Fields
Field
Type
Presence
Description
anonymousId
String
Optional
Sets the user ID for cases where there is no unique identifier for the user. Either userId
or anonymousId
is required.
userId
String
Required, if anonymousId
is not present.
Unique identifier for a particular user in your database.
context
Object
Optional
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
Object
Optional
A dictionary containing the destinations to be either enabled or disabled.
timestamp
DateTime
Optional
The timestamp of the message's arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ
. For example: 2022-02-01T19:14:18.381Z
traits
Object
Optional
Dictionary of the traits associated with the user, such as name
or email
For more details on the identify
call, refer to the RudderStack Events Specification.
6. Track
The track
call lets you record the customer events, i.e. the actions that they perform, along with any properties associated with them.
Request Type: POST
Request Format**:**
6.1. Sample Payload
6.2. Usage
CURL HTTPie
6.3. Accepted fields
Field
Type
Presence
Description
anonymousId
String
Optional
Sets the user ID for cases where there is no unique identifier for the user. Either userId
or anonymousId
is required.
userId
String
Required, if anonymousId
is not present.
Unique identifier for a particular user in your database.
context
Object
Optional
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
event
String
Required
Name of the event being performed by the user
properties
Object
Optional
Dictionary of the properties associated with a particular event.
integrations
Object
Optional
A dictionary containing the destinations to be either enabled or disabled.
timestamp
DateTime
Optional
The timestamp of the message's arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ
. For example: 2022-02-01T19:14:18.381Z
For more details on the track
call, refer to the RudderStack Events Specification.
7. Page
The page
call lets you record your website's page views with any additional relevant information about the viewed page.
Request Type: POST
Request Format**:**
7.1. Sample Payload
7.2. Usage
CURL HTTPie
7.3. Accepted Fields
Field
Type
Presence
Description
anonymousId
String
Optional
Sets the user ID for cases where there is no unique identifier for the user. Either userId
or anonymousId
is required.
userId
String
Required, if anonymousId
is not present.
Unique identifier for a particular user in your database.
context
Object
Optional
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
Object
Optional
A dictionary containing the destinations to be either enabled or disabled.
name
String
Required
Name of the page being viewed.
properties
Object
Optional
Dictionary of the properties associated with the page being viewed, such as url
and referrer
timestamp
DateTime
Optional
The timestamp of the message's arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ
. For example: 2022-02-01T19:14:18.381Z
For more details on the page
call, refer to the RudderStack Events Specification.
8. Screen
The screen
call lets you record whenever your user views their mobile screen with any additional relevant information about the screen.
The screen
call is the mobile equivalent of the page
call.
Request Type: POST
Request Format**:**
8.1. Sample Payload
8.2. Usage
CURL HTTPie
8.3. Accepted Fields
Field
Type
Presence
Description
anonymousId
String
Optional
Sets the user ID for cases where there is no unique identifier for the user. Either userId
or anonymousId
is required.
userId
String
Required, if anonymousId
is not present.
Unique identifier for a particular user in your database.
context
Object
Optional
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
Object
Optional
A dictionary containing the destinations to be either enabled or disabled.
name
String
Required
Name of the screen being viewed.
properties
Object
Optional
Dictionary of the properties associated with the page being viewed, such as url
and referrer
timestamp
DateTime
Optional
The timestamp of the message's arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ
. For example: 2022-02-01T19:14:18.381Z
For more details on the screen
call, refer to the RudderStack Events Specification.
9. Group
The group
call lets you link an identified user with a group such as a company, organization, or an account. It also lets you record any custom traits associated with that group, like the name of the company, the number of employees, etc.
Request Type: POST
Request Format**:**
9.1. Sample Payload
9.2. Usage
CURL HTTPie
9.3. Accepted Fields
Field
Type
Presence
Description
anonymousId
String
Optional
Sets the user ID for cases where there is no unique identifier for the user. Either userId
or anonymousId
is required.
userId
String
Required, if anonymousId
is not present.
Unique identifier for a particular user in your database.
context
Object
Optional
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
Object
Optional
A dictionary containing the destinations to be either enabled or disabled.
groupId
String
Required
Unique identifier of the group, as present in your database.
traits
Object
Optional
Dictionary of the properties or traits associated with the group, such as email
or name
.
timestamp
DateTime
Optional
The timestamp of the message's arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ
. For example: 2022-02-01T19:14:18.381Z
For more details on the group
call, refer to the RudderStack Events Specification.
10. Alias
The alias
call lets you merge different identities of a known user.
alias
is an advanced method that lets you change the tracked user's ID explicitly. This method is useful when managing identities for some of the downstream destinations.
The following destinations support the alias
call:
Amplitude (only supported by the JavaScript SDK via Cloud Mode)
Request Type: POST
Request Format**:**
10.1. Sample Payload
10.2. Usage
CURL HTTPie
10.3. Accepted Fields
Field
Type
Presence
Description
userId
String
Required, if anonymousId
is not present.
Unique identifier for a particular user in your database.
context
Object
Optional
Dictionary of information that provides context about a message. However, it is not directly related to the API call.
integrations
Object
Optional
A dictionary containing the destinations to be either enabled or disabled.
previousId
String
Required
The previous unique identifier of the user.
traits
Object
Optional
Dictionary of the properties or traits associated with the group, such as email
or name
.
timestamp
DateTime
Optional
The timestamp of the message's arrival. If you are passing the timestamp in the event, make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ
. For example: 2022-02-01T19:14:18.381Z
For more details on the alias
call, refer to the RudderStack Events Specification.
11. Batch
The batch
call allows you to send a series of identify
, track
, page
, group
and screen
requests in a single batch. This call helps you minimize the number of outbound requests, thus enabling better performance.
As mentioned earlier, RudderStack sets a maximum limit of 4 MB
per batch request and 32 KB
per call.
Request Type: POST
Request Format**:**
11.1. Sample Payload
11.2. Usage
CURL HTTPie
11.3. Accepted Fields
Field
Type
Presence
Description
batch
Array
Required
An array of identify
, track
, page
, group
and screen
calls. Each call must have a type
property and a valid method name.
12. Historical Imports
RudderStack lets you import any historical data by simply adding the timestamp
argument to any of your API calls. However, this can be done only for the destinations that accept historical time-stamped data, like Amplitude, Mixpanel, etc.
If you are tracking current events, leave out the timestamp
field. RudderStack will automatically add the timestamps to the event requests.
Contact Us
For more information on the HTTP API, you can contact us or start a conversation in our Slack community.
Last updated
Was this helpful?