Introduction to the REST API

Welcome to Stream's REST API documentation!

Please note

The REST documentation is recommended for advanced users that want to write their own API clients. Have a look below at the official clients, framework integrations, and community-contributed libraries.

Always feel free to get in touch at if you have questions.

Are you looking for a ready-made client or framework library?

If you're looking to get started quickly, official clients are available for a whole host of languages including Ruby, JavaScript, Python, PHP, Go, and more.

Framework integrations are also available for Rails, Django, and Laravel, in addition to community-contributed libraries for .NET and Scala.

You're currently not logged in. Log in so we can add your API key and other information in the documentation snippets elsewhere on this page.

First steps

1. Complete 'Getting Started'

Before you start writing your client, we recommend that you complete the getting started tutorial. It explains the core API concepts, and allows you to get familiar with Stream.

2. Review Official Clients

Reviewing the official Stream API clients is a great source of inspiration for writing your own client.

A good starting point is the official JavaScript client as it runs its test suite in the browser.

With the official JS client, you can see the tests and examine how the API requests are structured in your browser's network tab.

To see the tests, simply clone the stream-js package, and open test/browser/test.html in your browser.

You can review all of our open-source libraries at the official Stream GitHub page.

3. Browse Documentation

Stream's API consists of two authentication methods and eight REST endpoints. Be sure to review the basics.

Authentication Methods:

  • Application
  • Feed

REST Endpoints:

  • Activities
  • Feed
  • Feed Detail
  • Followers
  • Following
  • Following Detail
  • Batch Activity Add
  • Batch Follow

Get stuck? No worries at all, feel free to contact support at any time.



Location Support

The Stream API is currently available in 3 regions:

  • us-east
  • eu-west
  • singapore


Common Parameters

The following common GET parameters should be sent for every request:

Name Type Description
api_key string The API Key

Note: Every request should also include the appropriate authorization header.

JSON for POST Data

All POST data must be JSON encoded. This allows you to send complex data structures to the Stream API endpoint!


Depending on the resource being requested, Stream uses one of two authentication methods:

Both authentication methods create a signature that is specific to the requested resource (feed, or application).

When dealing with authentication tokens, you should keep in mind that tokens are like passwords. Never share tokens with untrusted parties.

Feed Authentication

Requests from a back-end application to the Stream API for a specific single feed use Feed Authentication to authenticate requests.

JSON Web Tokens (JWT)

This authentication method uses JSON Web Tokens (JWT) to authenticate each request. This is a standardized method to request permissions by signing a JSON formatted token with a known key, in this case your API Secret key. Read more about JWT at

Libraries are available in many languages for encoding and decoding JSON Web Tokens. Have a look at the libraries page to see if your language of choice is supported.

JWT usage for feed authentication

For feed authentication, the application should send a token that is signed with the API Secret of the Stream app. This token must include a permission scope compatible to the request that is being performed. Permission scopes are defined using the following fields: resource, action and feed_id.

The resource field of the JWT payload allows you to define which API endpoints can be accessed, you can pick one of the following:

The action field of the JWT payload allows you to define which HTTP verbs are allowed by a request:

The feed_id field in the JWT payload specifies for which feed the permissions specified before are granted. The value of this field should be a concatenation of the feed group's slug and the user_id of the feed instance. For example, if your feed group is called "news" and your user ID is 1234, the resulting concatenation would be "news1234". Similarly to the resource and action field, a single * character will grant the permissions on all feeds.

Sending an authenticated request

Once the token is generated correctly it is used to authenticate a request. This is done by setting two HTTP headers on the request:

  1. Stream-Auth-Type: jwt
  2. Authorization: <token>

Important: Some JWT libraries prefix the generated token with the string "Bearer". This prefix should be removed before sending the request to Stream.

Token examples

Below are some example tokens for different use cases:

// A token which allows every possible action on all feeds. Useful for
// development and server side, but unsuitable for usage on the client.
    "resource": "*",
    "action": "*",
    "feed_id": "*"


// A token which allows reading, modification and deletion of activities on
// the feed of the user with id 123.
    "resource": "feed",
    "action": "*",
    "feed_id": "user123"


// A token which allows reading the followers of the feed of user with id 123.
    "resource": "follower",
    "action": "read",
    "feed_id": "user123"


Application Authentication

When you are performing actions that are not specific to a single feed (such as application configuration, or batching), Application Authentication is used.

IETF: "Signing HTTP Messages"

Stream's Application Authentication implementation is based on the "Signing HTTP Messages" IETF Draft v3.

In order to authenticate, you need to send the HTTP Headers as indicated by the IETF Draft, as well as the X-Api-Key HTTP header containing your application's API key.

      X-Api-Key: api_key

Endpoint: Activities

The activities endpoint is located at
Authentication method: Feed Authentication
Resource Name:  activities

The Activities endpoint can be used to update activity data stored by Stream API.

This is useful when you want to update certain activity metadata used during feed ranking. Activities are updated by foreign_id. Changing the original time property of the activity is not allowed.


Name Type Description Default
activities list A JSON encoded list of activities to update. Maximum length is 100.

Endpoint: Feed

The feed endpoint is located at
Authentication method: Feed Authentication
Resource Name:  feed

The Feed endpoint is to retrieve activities in a feed (GET), or to submit an activity or list of activities (POST).


For retrieving the activities in a feed the following parameters as shown below are supported.

Name Type Description Default Optional
limit int The amount of activities requested from the APIs 25
id_gte int Filter the feed on ids greater than or equal to the given value
id_gt int Filter the feed on ids greater than the given value
id_lte int Filter the feed on ids smaller than or equal to the given value
id_lt int Filter the feed on ids smaller than the given value
offset int The offset 0

Passing both id_lt[e] and id_gt[e] is not supported.

Note on Pagination: Using id_lte for pagination is preferable to using offset.

Note on Aggregated Feeds: When using id_lte to paginate an aggregated feed, use the ID of the group that is returned from the API. Using an ID of an individual activity within the group will not work and result in an error.

If ranking is enabled on your feed group you can supply the ranking method to use by supplying the ranking method's slug on the following GET parameter:

Name Type Description Default Optional
ranking string The slug of the ranking method to use


For the POST request, you can either submit the data for one single activity or a list of activities. In addition to these base fields, extra data will be parsed as custom fields.

Name Type Description Default Optional
actor string The actor performing the activity
verb string The verb of the activity
object string The object of the activity
target string The optional target of the activity
time string The optional time of the activity, isoformat Current time
to list See the documentation on Targeting & "TO" support.
foreign_id string A unique ID from your application for this activity. IE: pin:1 or like:300

When you are sending a list of activities, the parameters are:

Name Type Description
activities list A JSON encoded list of activity data. The data for individual activities is the same as specified above.

Endpoint: Feed Detail

The feed detail endpoint is located at
Authentication method: Feed Authentication
Resource Name:  feed

The Feed Detail endpoint allows you to delete activities. The Stream API allows you to delete activities by the activity id generated by Stream, or by the foreign id you generate and put within your activity:

  • The activity id is returned to you in the response when the activity is first created.
  • The foreign id is a unique reference which represents the activity in your database.

Note: By setting foreign ids you ensure uniqueness and no longer need to store the Stream-generated activity id in your database. Read more about foreign ids versus activity ids over at the Stream general docs.


Note: Deleting an activity using your foreign id requires setting a foreign_id URL query parameter to "1":

Name Type Description Optional
foreign_id string Send a value of 1 to indicate you want to delete by foreign id

Endpoint: Followers

The followers endpoint is located at
Authentication method: Feed Authentication
Resource Name:  follower

The Followers endpoint is used to retrieve a paginated list of the given feed's followers (ie, which other feeds follow this feed). The resource is limited to the most recent 500 results.


Name Type Description Default Optional
limit int The amount of feeds following this feed requested from the APIs 25
offset int The offset, max 400 0

Endpoint: Following

The following endpoint is located at
Authentication method: Feed Authentication
Resource Name:  follower

The Following endpoint is for retrieving a list of feeds that this feed follows (GET), or to follow a target feed (POST). The resource is limited to the most recent 500 results.


Returns a paginated list of the feeds which this feed is following.

Name Type Description Default Optional
limit int The amount of followed feeds requested from the APIs 25
offset int The offset, max 400 0
filter string List of comma separated feed ids to filter on. IE user:1,user:2. Allows you to check if a certain feed is followed.


Follows a target feed.
Name Type Description Default Optional
target string The target feed this feed should follow. For example user:44.
activity_copy_limit integer How many activities should be copied from the target feed, max 1000 300

Endpoint: Following Detail

The following detail endpoint is located at
Authentication method: Feed Authentication
Resource Name:  follower

The Following Detail endpoint allows you to unfollow a target feed.


Name Type Description Default Optional
keep_history string When provided the activities from target feed will not be kept in the feed

Target is in the syntax of [feed]:[id]. For example, "user:1".

Note: Unfollow target's activities are purged from the feed unless the keep_history parameter is provided.

Endpoint: Batch Activity Add

The batch follow endpoint is located at
Authentication method: Application Authentication

The Batch Activity Add endpoint allows you to add an activity to multiple feeds in one single request.

Batch Activity Add has a limit of 5,000 target feeds. Requests that exceed this limit will return an error.


Name Type Description
feeds list The list of feeds where the activity will be stored eg. ['user:1', 'flat:2' ]
activity object A JSON encoded activity object (see feed endpoint for reference)

Endpoint: Follow Many

The follow many endpoint is located at
Authentication method: Application Authentication

The Follow Many endpoint allows you to create multiple follows in one single batch request.

Follow Many has is a limit of 2,500 follows per request.


Note: The `activity_copy_limit` parameter is a query parameter.

Name Type Description Default Optional
list A JSON encoded list of a follow object {'source': 'source:id', 'target': 'target:id'} . eg. [{'source': 'flat:1', 'target': 'user:2'}, ]
activity_copy_limit integer How many activities should be copied from the target feed, max 1000 300


All clients should support several options:

API Location (Region)

Location/Region should be configurable when initializing the Stream client.

Request Timeout

The request timeout should be configurable. We recommend 3 seconds as a default.

On average, it takes ~60ms to retrieve your feed. However, it is possible for network latency to spike, which is why we recommend setting a timeout.

Best Practices

Here's a brief list of best practices that we recommend when building a new API SDK for interacting with Stream:

Test Code Coverage (>95%)

We recommend building both unit and integration tests, and ensuring a code coverage above 95%.

Code Examples - Every API Endpoint

Document the API calls for every operation.

Check out the README of the stream-python repo for a good starting point.

Input Validation

Feed slugs and user ids need to match the \w+ regular expression. Your client should validate input before sending an API call.

Error Mapping

Errors from the Stream API should be mapped to exception classes and properly raised.

Software Licensing

We recommend using the MIT or BSD license when releasing open-source software.

Offering Support

If you release your software as open-source, and place it on GitHub, we ask that you pay close attention to any issues and pull requests by other community members. If your SDK gains significant support, we may also request to take over your open-source project as an officially-supported library so we can assist with support efforts.

Naming Conventions

We try to keep our variable names consistent amongst the various API clients, except in the case where common lint-checker software will raise too many errors. This section explains some common terminology we use in our SDK libraries.