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.
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.
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.
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 jwt.io/introduction.
Libraries are available in many languages for encoding and decoding JSON Web Tokens.
Have a look at the jwt.io 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:
Stream-Auth-Type: jwt
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.
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.
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.
POST
Name
Type
Description
Default
list
A JSON encoded list of activities to update. Maximum length is 100.
The Feed endpoint is to retrieve activities in a feed (GET),
or to submit an activity or list of activities (POST).
GET
For retrieving the activities in a feed the following parameters as shown below are supported.
Note: The id_lte pagination type is preferable to the traditional offset approach.
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
✓
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
✓
POST
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.
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.
DELETE
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
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.
GET
Name
Type
Description
Default
Optional
limit
int
The amount of feeds following this feed requested from the APIs
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.
GET
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.
✓
POST
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
The Batch Follow endpoint allows you to create multiple follows in one single batch request.
POST
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
✓
Options
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.