API Basics

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 support@getstream.io 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, Java, PHP, Go, C# and more. Framework integrations are also available for Rails, Django, and Laravel.

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
  • Reactions
  • Reactions Detail
  • Reactions pagination
  • Open Graph
  • Collection
  • Collection Detail
  • Batch Collection
  • Files
  • Images
  • User
  • User Detail

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

Basics

Base API URL:  https://api.stream-io-api.com/api/v1.0/

Location Support

The Stream API is currently available in 3 regions:

  • us-east
  • eu-west
  • singapore

Examples:

https://us-east-api.stream-io-api.com/api/v1.0/
https://eu-west-api.stream-io-api.com/api/v1.0/
https://singapore-api.stream-io-api.com/api/v1.0/

Common Parameters

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

NameTypeDescription
api_keystringYOUR_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!

Authentication

API Keys and Token

Every API request to Stream must include: the API Key of the app performing the request and an authentication token generated using the API Key secret.

Token must be a JWT token including a signature generated with the HS256 algorithm.

You can find more information on JWT at jwt.io/introduction. Libraries to generate JWT are available for most programming languages. The full list is available here. The authentication token must include the correct claims (also called payload). A token valid for a type of request or for a user_id might not be valid for another one. Your application should generate the appropriate token; when using client-side auth, each user should have its own unique token.

Sending an authenticated request

All API requests to Stream must include a query parameter called api_key with the API Key in use.

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.

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

Stream uses JWT to provide two types of authentication:

Server-Side Authentication

Requests from a back-end application to the Stream API for a specific single resource use Server-Side Authentication to authenticate requests.

JWT usage for server-side authentication

For server-side 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 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:

Resource NameAPI Endpoint
activitiesActivities Endpoint
feedFeed Endpoint
followerFollowing + Followers Endpoint
*Allow access to any resource

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

Action NameHTTP Verb(s)
readGET, OPTIONS, HEAD
writePOST, PUT, PATCH
deleteDELETE
*The JWT has permission to all HTTP verbs

The feed_id field in the JWT payload specifies for which feed/resource 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.

Token examples

Below are some example tokens for different use cases:

These examples use a fake flat feed called "fake_flat_feed"

// A token which allows every possible action on all feeds. Useful for
// development and server side, but unsuitable for usage on client applications.
{
    "resource": "*",
    "action": "*",
    "feed_id": "*"
}
// the resulting JWT encoded string would look like this:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNvdXJjZSI6IioiLCJhY3Rpb24iOiIqIiwiZmVlZF9pZCI6IioifQ.FnH6LrB0ORV8Jb8P3Nca1Ks5wdPA0oMEArd7voCHnQo"

// A token which allows reading, modification and deletion of activities on
// the "fake_flat_feed" feed with a user id 123.
{
    "resource": "feed",
    "action": "*",
    "feed_id": "fake_flat_feed123"
}
// the resulting JWT encoded string would look like this:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNvdXJjZSI6ImZlZWQiLCJhY3Rpb24iOiIqIiwiZmVlZF9pZCI6ImZha2VfZmxhdF9mZWVkMTIzIn0.YF8a4kY2mFaDemx4zhM8PURWbPDIRoeuwHB9lvtoDlU"

// A token which allows reading the followers of the "fake_flat_feed" feed for user 123.
{
    "resource": "follower",
    "action": "read",
    "feed_id": "fake_flat_feed123"
}
// the resulting JWT encoded string would look like this:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXNvdXJjZSI6ImZvbGxvd2VyIiwiYWN0aW9uIjoicmVhZCIsImZlZWRfaWQiOiJmYWtlX2ZsYXRfZmVlZDEyMyJ9.M5p4t6MrZC42yFhm4zu4tuWOuXlfK_WBE2SETTlWHHk"

Client-Side Authentication

Requests from a front-end application to the Stream API to certain endpoints use Client-Side Authentication to authenticate requests.

JWT usage for client-side authentication

When using Stream on web or mobile apps, you can use a different kind of auth that allows you to authenticate users instead of your server-side application. This authentication enforces per-user permission checks.

Client-side auth is selected when a JWT token includes user_id in the payload. You can include additional fields in the JWT payload as long as they don't overlap with the server-side authentication ones.

A common approach is to have your users authenticate with your app server-side and to provision a user token so that API calls to Stream can be done on their behalf directly on your mobile/web app.

Token example

This example uses the userID "bob_johnson_1"

# The token claims contain only user_id
#   {
#     "user_id": "bob_johnson_1"
#   }
// the resulting JWT encoded string would look like this:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiYm9iX2pvaG5zb25fMSJ9.wyzuDl1sfQOaBzzJQUiQdz00IP31xmq-nfqBfEAF660"

This example uses the userID "bob_johnson_1"

# The token claims contain user_id and extra fields
#   {
#     "user_id": "bob_johnson_1",
#     "user_group": "admins"
#   }
// the resulting JWT encoded string would look like this:
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiYm9iX2pvaG5zb25fMSIsInVzZXJfZ3JvdXAiOiJhZG1pbnMifQ.VQ626qhTrmCsjSQ6FDLaV8EKSJDkrGYJScSHeRji5YU"

Endpoints

Activities

The activities endpoint is located at (enrich)/activities/

Authentication method: Server-Side Authentication

Resource Name: activities

The Activities endpoint can be used to update activity data stored by Stream API (POST) or to retrieve specific activities by either ID or the combination of foreign ID and timestamp (GET).

POST

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.

NAMETYPEDESCRIPTIONDEFAULT
activitieslistA JSON encoded list of activities to update. Maximum length is 100.

The following example uses your API Secret to generate the JWT encoded string

  # the JWT token would be built using a payload similar to:
  #{
  #    "resource": "activities",
  #    "action": "write",
  #    "feed_id": "*"
  #}

curl -i -X POST -d "{\"activities\":[{\"actor\":\"user:789\",\"verb\":\"post\",\"object\":\"story:abc123\",\"foreign_id\":\"story:123\",\"time\":\"2017-02-23T22:57:07.099Z\",\"message\":\"My new message\"}]}" \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/activities/?api_key=YOUR_API_KEY"

GET

URI parameters

NAMETYPEDESCRIPTION
enrichstringIf URI contains word "enrich", the response will be enriched.

Query parameters

NAMETYPEDESCRIPTIONOPTIONAL
idsstringA comma separated list of activity IDs. Maximum length is 100.
foreign_idsstringA comma separated list of activity foreign IDs. Maximum length is 100, and must match the length of timestamps.
timestampsstringA comma separated list of activity timestamps. Maximum length is 100, and must match the length of foreign_ids.
withRecentReactionsbooleanIf true activity object will have attribute "latest_reactions" that contains list of recently created reactions
recentReactionsLimitintSpecify number of reactions in the "latest_reactions" attribute, maximum value is 25.
withOwnReactionsbooleanIf true activity object will have attribute "own_reactions" that contains list of reactions created by the user himself.
withReactionCountsbooleanIf true activity object will have attribute "reaction_counts" that contains number of reactions for each kind

The following example uses your API Secret to generate the JWT encoded string

# the JWT token would be built using a payload similar to:
#{
#    "resource": "activities",
#    "action": "read",
#    "feed_id": "*"
#}

# retrieve by ID
curl -i --request GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/activities/?api_key=YOUR_API_KEY&ids=4ef6ee4e-79f1-11e8-8080-8001277e7b5f,ae41abaa-a1fe-4186-861a-bd244fe5997d"

# retrieve by foreign ID + timestamp
curl -i --request GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/activities/?api_key=YOUR_API_KEY&foreign_ids=like:2,post:3&timestamps=2018-07-08T14:09:36.000000,2018-07-09T20:30:40.000000"

Activity

The activity endpoint is located at activity/

Authentication method: Server-Side Authentication

Resource Name: activities

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

POST

For updating only parts of one or more activities by changing, adding, or removing fields.

NAMETYPEDESCRIPTIONDEFAULT
changeslistA JSON encoded list of changes to apply. Maximum length is 100.

Within every change set it is possible to reference the target fields directly or using the dotted notation ("grandfather.father.child"), given that it respects the existing hierarchy.

Every value of the set object will replace the original value, while the ones int the unset list will be removed from the activity.

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
idstringThe target activity ID.
foreign_idstringThe target activity foreign ID (matched with time).
timestringThe target activity timestamp (matched with foreign_id).
setobjectAn object containing the set operations, where keys are the target fields and the values are the values to be set. Maximum 25 top level keys.
unsetlistA list of strings containing the fields to be removed from the activity. Maximum 25 keys.

Note: the keys of set and unset must not collide.

The following example uses your API Secret to generate the JWT encoded string

# the JWT token would be built using a payload similar to:
#{
#    "resource": "activities",
#    "action": "*",
#    "feed_id": "*"
#}

curl -i -X POST -d "{\"changes\": [{\"id\":\"907a8010-1d84-11e9-9457-9cb6d0925edd\",\"set\":{\"product\":{\"sku\":123,\"name\":\"zoo\"},\"colors.red.hex\":\"FF0000\"},\"unset\":[\"popularity\",\"price.usd\"]}, {\"id\":\"65bca63a-7d61-48e8-be9d-c6665a008196\",\"set\":{\"product\":{\"sku\":1234,\"name\":\"foo\"},\"colors.blue.hex\":\"0000FF\"},\"unset\":[\"popularity\",\"price.eur\"]}]}" \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/activity/?api_key=YOUR_API_KEY"

Feed

The feed endpoint is located at (enrich)/feed/(feed_slug)/(user_id)/

Authentication method: Server-Side 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).

GET

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

URI parameters

NAMETYPEDESCRIPTION
enrichstringIf URI contains word "enrich", the response will be enriched.

Query parameters

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
limitintThe amount of activities requested from the APIs25
id_gteintFilter the feed on ids greater than or equal to the given value
id_gtintFilter the feed on ids greater than the given value
id_lteintFilter the feed on ids smaller than or equal to the given value
id_ltintFilter the feed on ids smaller than the given value
offsetintThe offset0
withRecentReactionsbooleanIf true activity object will have attribute "latest_reactions" that contains list of recently created reactions
recentReactionsLimitintSpecify number of reactions in the "latest_reactions" attribute, maximum value is 25.
withOwnReactionsbooleanIf true activity object will have attribute "own_reactions" that contains list of reactions created by the user himself.
withReactionCountsbooleanIf true activity object will have attribute "reaction_counts" that contains number of reactions for each kind

Passing both id_lt[e]andid_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:

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
rankingstringThe slug of the ranking method to use

The following example uses a fake aggregated feed within your application called "fake_aggregated_feed", and assumes a user id of 123.

# the JWT token would be built using a payload similar to:
#{
#    "resource": "feed",
#    "action": "read",
#    "feed_id": "fake_aggregated_feed123"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_aggregated_feed/123/?api_key`={{apiKey}`}"

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.

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
actorstringThe actor performing the activity
verbstringThe verb of the activity
objectstringThe object of the activity
targetstringThe optional target of the activity
timestringThe optional time of the activity, isoformatCurrent time
tolistSee the documentation on Targeting & "TO" support.
foreign_idstringA 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:

NAMETYPEDESCRIPTION
activitieslistA JSON encoded list of activity data. The data for individual activities is the same as specified above.

The following example uses a fake flat feed in your application called "fake_flat_feed", and assumes a user id of 123.

# the JWT token would be built using a payload similar to:
#{
#    "resource": "feed",
#    "action": "write",
#    "feed_id": "fake_flat_feed"
#}

curl -i -X POST -d "{\"actor\":\"user:789\",\"verb\":\"post\",\"object\":\"story:abc123\",\"foreign_id\":\"story:123\",\"time\":\"2017-02-23T22:57:07.099Z\",\"message\":\"My Example Post\"}" \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_flat_feed/123/?api_key=YOUR_API_KEY"

Feed Detail

The feed detail endpoint is located atfeed/(feed_slug)/(user_id)/(activity_id|foreign_id)/

Authentication method: Server-Side 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.

DELETE

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

NAMETYPEDESCRIPTIONOPTIONAL
foreign_idstringSend a value of 1 to indicate you want to delete by foreign id

The following example uses a fake flat feed in your application called "fake_flat_feed", and assumes a user id of 789 and foreign id of "abc123".

# the JWT token would be built using a payload similar to:
#{
#    "resource": "feed",
#    "action": "delete",
#    "feed_id": "fake_flat_feed789"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_flat_feed/789/abc123/?foreign_id=1&api_key=`YOUR_API_KEY`"

Followers

The followers endpoint is located at feed/(feed_slug)/(user_id)/followers/

Authentication method: Server-Side 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.

GET

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
limitintThe amount of feeds following this feed requested from the APIs25
offsetintThe offset, max 4000

The following example uses a fake flat feed in your application called "fake_flat_feed", and assumes a user ID of 789

# the JWT token would be built using a payload similar to:
#{
#    "resource": "follower",
#    "action": "read",
#    "feed_id": "fake_flat_feed123"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_flat_feed/123/followers/?api_key`={{apiKey}`}"

Following

The following endpoint is located at feed/(feed_slug)/(user_id)/follows/

Authentication method: Server-Side 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.

GET

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

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
limitintThe amount of followed feeds requested from the APIs25
offsetintThe offset, max 4000
filterstringList of comma separated feed ids to filter on. IE user:1,user:2. Allows you to check if a certain feed is followed.

The following example uses a ('flat',) feed in your application called "fake_flat_feed" and assumes a user id 123.

# the JWT token would be built using a payload similar to:
#{
#    "resource": "follower",
#    "action": "read",
#    "feed_id": "fake_flat_feed123"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_flat_feed/123/follows/?api_key`={{apiKey}`}"

POST

Follows a target feed.

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
targetstringThe target feed this feed should follow. For example user:44.
activity_copy_limitintegerHow many activities should be copied from the target feed, max 1000100

The following example uses a ('flat',) feed in your application called "fake_flat_feed" and assumes a user id 123 follows another user with an id of 789. The example will also set the activity_copy_limit to 100.

# the JWT token would be built using a payload similar to:
#{
#    "resource": "follower",
#    "action": "write",
#    "feed_id": "fake_flat_feed123"
#}

curl -i -X POST -d "{\"target\":\"fake_flat_feed:789\"}" \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_flat_feed/123/follows/?api_key`={{apiKey}`}&activity_copy_limit=100"

Following Detail

The following detail endpoint is located at feed/(feed_slug)/(user_id)/following/(target)/

Authentication method: Server-Side Authentication

Resource Name: follower

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

DELETE

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
keep_historystringWhen 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.

The following example uses a ('flat',) feed in your application called "fake_flat_feed" and assumes a user id 123 is going to unfollow another user with an id of 789.

    # the JWT token would be built using a payload similar to:
    #{
    #    "resource": "follower",
    #    "action": "delete",
    #    "feed_id": "fake_flat_feed123"
    #}

    curl -i -X DELETE \
    -H "Content-Type: application/json" \
    -H "Stream-Auth-Type: jwt" \
    -H "Authorization: TOKEN" \
    "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/fake_flat_feed/123/follows/fake_flat_feed:789/?api_key=YOUR_API_KEY"

Batch Activity Add

The batch follow endpoint is located at feed/add_to_many/

Authentication method: Server-Side Authentication

Resource Name: feed

Feed ID: *

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.

POST

NAMETYPEDESCRIPTION
feedslistThe list of feeds where the activity will be stored eg. ['user:1', 'flat:2' ]
activityobjectA JSON encoded activity object (see feed endpoint for reference)

The following example uses a fake flat feed in your application called "fake_flat_feed", and adds one activity to this feed for users with id values of 123 and 789.

# the JWT token would be built using a payload similar to:
#{
#    "resource": "feed",
#    "action": "write",
#    "feed_id": "*"
#}

  curl -i -X POST -d "{\"feeds\":[\"fake_flat_feed:123\",\"fake_flat_feed:789\"],\"activity\":{\"actor\":\"User:2\",\"verb\":\"pin\",\"object\":\"Place:42\",\"target\":\"Board:1\"}}" \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/feed/add_to_many/?api_key=YOUR_API_KEY"

Follow Many

The follow many endpoint is located at follow_many/

Authentication method: Server-Side Authentication

Resource Name: follower

Feed ID: *

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

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

POST

Note: The activity_copy_limit parameter is a query parameter.

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
listA JSON encoded list of a follow object {'source': 'source:id', 'target': 'target:id'} . eg. [{'source': 'flat:1', 'target': 'user:2'}, ]
activity_copy_limitintegerHow many activities should be copied from the target feed, max 1000100

The following example uses a fake flat feed in your application called "fake_flat_feed", and assumes user 123 will follow other users on that feed who have ids of 456 and 789. We will set the activity_copy_limit to a value of 300.

# the JWT token would be built using a payload similar to:
#{
#    "resource": "follower",
#    "action": "write",
#    "feed_id": "*"
#}

curl -i -X POST -d "[{\"source\":\"flat:123\",\"target\":\"flat:456\"},{\"source\":\"flat:123\",\"target\":\"flat:798\"}]" \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/follow_many/?activity_copy_limit=300&api_key=`YOUR_API_KEY`"

Reaction

The reactions endpoint is located at reaction/

Authentication method: Client-Side Authentication

The reaction endpoint can be used to add reactions to Stream API.

POST

Request data

NAMETYPEDESCRIPTIONOPTIONAL
kindstringType of reaction. Must not be empty or longer than 255 characters.
activity_idstringActivity ID for the reaction. Must be a valid activity ID.
user_idstringuser_id of the reaction. Must not be empty or longer than 255 characters.
dataobjectExtra data of the reaction
target_feedslistTarget feeds for the reaction. List of feed ids (e.g.: timeline:bob)
parentstringID of the parent reaction. If provided, it must be the ID of a reaction that has no parents.

Note: when using client-side auth the user_id field must not be provided as the value will be taken from the user token.

Note: If a reaction with the same ID already exists, the request will error with code 409 Conflict.

Returned reaction object schema

NAMETYPEDESCRIPTIONOPTIONAL
idstringReaction ID.
kindstringType of reaction.
activity_idstringActivity ID for the reaction.
user_idstringuser_id of the reaction.
userobjectUser of the reaction
dataobjectExtra data of the reaction
created_atdateWhen the reaction was created.
updated_atdateWhen the reaction was last updated.
parentstringID of the parent reaction. Empty unless the reaction is a child reaction.
latest_childrenobjectChildren reactions, grouped by reaction type.
children_countsobjectChild reaction count, grouped by reaction kind.

The following example assumes the user id of "bob" and an activity id of "65bca63a-7d61-48e8-be9d-c6665a008196"

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X POST -d "{\"user_id\":\"bob\",\"kind\":\"like\",\"activity_id\": \"65bca63a-7d61-48e8-be9d-c6665a008196\",\"data\":{\"extra\":\"data\"}}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/reaction/?api_key=YOUR_API_KEY"

Reaction detail

The reactions endpoint is located at reaction/(id)/

Authentication method: Client-Side Authentication

The reaction detail endpoint can be used to retrieve (GET) a reaction, update (PUT) reaction data and target feeds and delete (DELETE) reactions.

GET

The returned object schema is described in the reactions endpoint

The following example assumes the user id of "bob" and a reaction id of "65bca63a-7d61-48e8-be9d-c6665a008196"

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/reaction/65bca63a-7d61-48e8-be9d-c6665a008196/?api_key=YOUR_API_KEY"

DELETE

Will return an empty response on success.

The following example assumes the user id of "bob" and a reaction id of "65bca63a-7d61-48e8-be9d-c6665a008196"

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/reaction/65bca63a-7d61-48e8-be9d-c6665a008196/?api_key=YOUR_API_KEY"

PUT

Request data

NAMETYPEDESCRIPTIONOPTIONAL
dataobjectExtra data of the reaction
target_feedslistTarget feeds for the reaction. List of feed ids (e.g.: timeline:bob)

Returns the updated reaction object. The object schema is described in the reactions endpoint

The following example assumes the user id of "bob" and a reaction id of "65bca63a-7d61-48e8-be9d-c6665a008196"

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X PUT -d "{\"data\":{\"extra\":\"modified\"},\"target_feeds\":[\"user:jimmy\"]}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/reaction/65bca63a-7d61-48e8-be9d-c6665a008196/?api_key=YOUR_API_KEY"

Reaction pagination

The Reaction pagination endpoint is located at reaction/(lookup_attr)/(lookup_value)/(kind)/

Authentication method: Client-Side Authentication

The reaction pagination endpoint can be used to fetch (GET) reactions based on certain criteria.

GET

URI parameters

NAMETYPEDESCRIPTIONOPTIONAL
lookup_attrstringName of the reaction attribute to paginate on. Can be activity_id, reaction_id or user_id.
lookup_valuestringValue to use depending if paginating reactions for an activity, from a user or reactions of a reaction.
kindstringType of reaction( e.g.: like).

Query parameters

NAMETYPEDESCRIPTIONOPTIONAL
limitstringAmount of reactions requested from the API. Default: 10. Max: 25. Values larger than the max will be ignored and the max limit will be used.
id_gtestringFilter the reactions on ids greater than or equal to the given value
id_gtstringFilter the reactions on ids greater than the given value
id_ltestringFilter the reactions on ids smaller than or equal to the given value
id_ltstringFilter the reactions on ids smaller than the given value
with_activity_databooleanReturns the activity data when lookup_attr is activity_id

Note: passing both id_lt[e]andid_gt[e] is not supported.

Note: when using id_lt[e] the reactions are ordered by the created_at field, in descending order.

Note: when using id_gt[e] the reactions are ordered by the created_at field, in ascending order.

Response object

NAMETYPEDESCRIPTION
resultslistList of reactions. The reaction object schema can be found here
activityobjectThe activity data, this field is returned only when with_activity_data is sent.
nextstringA url string that can be used to fetch the next page of reactions.

The following example assumes the user id of "bob" and a reaction id of "65bca63a-7d61-48e8-be9d-c6665a008196"

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/reaction/user_id/bob/?api_key=YOUR_API_KEY&id_lte=65bca63a-7d61-48e8-be9d-c6665a008196"

Open Graph

The Open Graph endpoint is located at og/

Authentication method: Client-Side Authentication

The Open Graph endpoint can be used to scrape (GET) open graph data from a website.

The Open Graph protocol enables any web page to become a rich object in a social graph. More information can be found here.

GET

Query parameters

NAMETYPEDESCRIPTION
urlstringURL to scrape.

Response object

NAMETYPEDESCRIPTIONOPTIONAL
titlestringValue of the title OG field.
typestringValue of the type OG field.
urlstringValue of the url OG field.
sitestringValue of the site OG field.
site_namestringValue of the site_name OG field.
descriptionstringValue of the description OG field.
determinerstringValue of the determiner OG field.
localestringValue of the locale OG field.
imageslistList of og images
videoslistList of og videos
audioslistList of og audios

OG Image object

NAMETYPEDESCRIPTIONOPTIONAL
imagestringValue of the image OG field.
urlstringValue of the url OG field.
secure_urlstringValue of the secure_url OG field.
widthstringValue of the width OG field.
heightstringValue of the height OG field.
typestringValue of the type OG field.
altstringValue of the alt OG field.

OG Video object

NAMETYPEDESCRIPTIONOPTIONAL
imagestringValue of the image OG field.
urlstringValue of the url OG field.
secure_urlstringValue of the secure_url OG field.
widthstringValue of the width OG field.
heightstringValue of the height OG field.
typestringValue of the type OG field.
altstringValue of the alt OG field.

OG Audio object

NAMETYPEDESCRIPTIONOPTIONAL
audiostringValue of the audio OG field.
urlstringValue of the url OG field.
secure_urlstringValue of the secure_url OG field.
typestringValue of the type OG field.

The following example assumes the user id of "bob" and a reaction id of "65bca63a-7d61-48e8-be9d-c6665a008196"

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/og/?api_key=YOUR_API_KEY&url=http://ogp.me"

Collection

The collection endpoint is located at collections/(collection_name)/

Authentication method: Client-Side Authentication

The collection endpoint can be used to add collection objects(POST) to a specific collection.

POST

Request data

NAMETYPEDESCRIPTIONOPTIONAL
idstringCollection object ID
user_idstringuser_id of the collection object.
dataobjectCollection object data

Note: when using client-side auth the user_id field must not be provided as the value will be taken from the user token.

Note: If a collection object with the same ID already exists, the request will error with code 409 Conflict.

Returned collection object schema

NAMETYPEDESCRIPTION
collectionstringCollection name
idstringCollection object ID.
foreign_idstringForeignID of the collection object. The format is <collection_name>:<collection_object_id>
dataobjectCollection object data
created_atdateWhen the collection object was created.
updated_atdateWhen the collection object was last updated.

The following example assumes the user id of "bob" and the collection name "col1".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X POST -d "{\"data\":{\"extra\":\"fields\",\"flag\":false}}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/col1/?api_key=YOUR_API_KEY"

Collection detail

The collection endpoint is located at collections/(collection_name)/(id)/

Authentication method: Client-Side Authentication

The collection detail endpoint can be used can be used to retrieve (GET), update (PUT) and delete (DELETE) collection objects.

GET

The returned object schema is described in the collection endpoint.

The following example assumes the user id of "bob",the collection name "col1" and the collection object id "123".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/col1/123/?api_key=YOUR_API_KEY"

PUT

Request data

NAMETYPEDESCRIPTION
dataobjectCollection object data

The returned object schema is described in the collection endpoint.

The following example assumes the user id of "bob",the collection name "col1" and the collection object id "123".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X PUT -d "{\"data\":{\"modified\":\"fields\",\"modified\":true}}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/col1/123/?api_key=YOUR_API_KEY"

DELETE

Will return an empty response on success.

The following example assumes the user id of "bob",the collection name "col1" and the collection object id "123".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/col1/123/?api_key=YOUR_API_KEY"

Collections batch

The collections endpoint is located at collections/

Authentication method: Server-Side Authentication

Resource Name: collections

Feed ID: *

The collections detail endpoint can be used can be used to retrieve (GET), upsert (POST) and delete (DELETE) multiple collection objects at once.

GET

Query parameters

NAMETYPEDESCRIPTION
foreign_idsstringComma separated list of foreign ids. A foreign id has the format <collection_name>:<collection_object_id>. The maximum number of foreign ids is 1000. E.g.: collection1:id1,collection1:id2,collection3:id5

Returned object schema

NAMETYPEDESCRIPTION
responseobjectResponse object containing a data field which is an array of collection objects. The schema for the objects can be found in the collection docs.

Example response object:

{
    "response": {
        "data": [
            {
                "collection": "collection1",
                "created_at": "2018-11-29T12:03:52.792967Z",
                "data": {
                    "flag": false,
                    "field": "value"
                },
                "foreign_id": "collection1:id1",
                "id": "asdf",
                "updated_at": "2018-11-29T12:28:20.735841Z"
            }
        ]
    }
}

The following example assumes the collection "col1" with object ids "id1" and "id2" and the collection "col3" with object id "id5"

# the JWT token would be built using a payload similar to:
#{
#    "resource": "collections",
#    "action": "read",
#    "feed_id": "*"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/?api_key=YOUR_API_KEY&&foreign_ids=col1:id1,col2:id2,col3:id5"

POST

Request data

NAMETYPEDESCRIPTION
dataobjectA map between collection names and the collection objects that will be upserted

Example request data:

{
    "data": {
        "collection1": [
            {
                "id": "id1",
                "data": {
                    "field": "value",
                    "flag": false
                },
                "user_id": "user1"
            },
            {
                "id": "id2",
                "data": {
                    "field": "modify"
                }
            }
        ],
        "collection2": [
            {
                "id": "id23",
                "data": {
                    "user": "data"
                }
            }
        ]
    }
}

Note: You cannot have collection objects with the same id within the same collection.

The endpoint returns a clone of the data field from the request data upon success.

The following example assumes the collection "col1" with object ids "id1" and "id2" and the collection "col3" with object id "id5"

# the JWT token would be built using a payload similar to:
#{
#    "resource": "collections",
#    "action": "write",
#    "feed_id": "*"
#}


curl -i -X POST -d "{\"data\":{\"col1\":[{\"id\":\"id1\",\"data\":{\"field\":\"value\",\"flag\":false},\"user_id\":\"user1\"},{\"id\":\"id2\",\"data\":{\"field\":\"modify\"}}],\"collection3\":[{\"id\":\"id5\",\"data\":{\"user\":\"data\"}}]}}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/?api_key=YOUR_API_KEY"

DELETE

Note: You can only delete objects from a single collection per request.

Query parameters

NAMETYPEDESCRIPTION
collection_namestringThe name of the collection.
idsstringComma separated list of collection object ids. E.g.: id1,id2,id3

Will return an empty response on success.

The following example assumes the collection "col1" with object ids "id1" and "id2"

# the JWT token would be built using a payload similar to:
#{
#    "resource": "collections",
#    "action": "delete",
#    "feed_id": "*"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/collections/?api_key=YOUR_API_KEY&&collection_name=col1&ids=id1,id2"

Files

The files endpoint is located at files/

Authentication method: Server-Side Authentication

Resource Name: files

Feed ID: *

Authentication method: Client-Side Authentication

The files endpoint can be used can be used to upload (POST) and delete (DELETE) files to and from Stream API.

POST

Request data

NAMETYPEDESCRIPTION
filefileFile to upload. Must be sent as form data (Content-Type: multipart/form-data).

Returned object schema

NAMETYPEDESCRIPTION
filestringPublicly reachable CDN URL of the uploaded file.

The following example assumes the user id of "bob" and the local file path "some_file".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X POST \
  -F "file=@some_file" \
  -H "Content-Type: multipart/form-data" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/files/?api_key=YOUR_API_KEY"

DELETE

Query parameters

NAMETYPEDESCRIPTION
urlstringURL of the file to delete. This is the URL returned by the POST request.

Will return an empty response on success.

The following example assumes the user id of "bob" and the file url "https://cdn.example.com/file/".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/files/?api_key=YOUR_API_KEY&url=https://cdn.example.com/file"


# You can also use server-side authentication.
# the JWT token would be built using a payload similar to:
#{
#    "resource": "files",
#    "action": "delete",
#    "feed_id": "*"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/files/?api_key=YOUR_API_KEY&url=https://cdn.example.com/file"

Images

The images endpoint is located at images/

Authentication method: Server-Side Authentication

Resource Name: files

Feed ID: *

Authentication method: Client-Side Authentication

The images endpoint can be used can be used to process(GET), upload (POST) and delete (DELETE) images.

GET

Query parameters

NAMETYPEDESCRIPTIONDEFAULTOPTIONAL
urlstringURL of the image to process. This is the URL returned by the POST request.
resizestringStrategy used to adapt the image the new dimensions. Allowed values are: clip, crop, scale, fill.clip
cropstringCropping modes as a comma separated list. Allowed values are top, bottom, left, right, center.center
wnumberWidth of the processed image.
hnumberGeight of the processed image.

Returned object schema

NAMETYPEDESCRIPTION
filestringPublicly reachable CDN URL of the processed image.

POST

Request data

NAMETYPEDESCRIPTION
filefileImage to upload. Must be sent as form data (Content-Type: multipart/form-data).

Returned object schema

NAMETYPEDESCRIPTION
filestringPublicly reachable CDN URL of the uploaded image.

The following example assumes the user id of "bob" and the local image path "some_image".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X POST \
  -F "file=@some_image" \
  -H "Content-Type: multipart/form-data" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/images/?api_key=YOUR_API_KEY"

DELETE

Query parameters

NAMETYPEDESCRIPTION
urlstringURL of the image to delete. This is the URL returned by the POST request.

Will return an empty response on success.

The following example assumes the user id of "bob" and the image url "https://cdn.example.com/image/".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/images/?api_key=YOUR_API_KEY&url=https://cdn.example.com/image"

# You can also use server-side authentication.
# the JWT token would be built using a payload similar to:
#{
#    "resource": "files",
#    "action": "delete",
#    "feed_id": "*"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/images/?api_key=YOUR_API_KEY&url=https://cdn.example.com/image"

User

The user endpoint is located at user/

Authentication method: Server-Side Authentication

Resource Name: users

Feed ID: *

Authentication method: Client-Side Authentication

The user endpoint can be used to add a user(POST) via Stream API.

POST

Request data

NAMETYPEDESCRIPTION
idstringUser ID. Must not be empty or longer than 255 characters.
dataobjectUser additional data.

Query parameters

NAMETYPEDESCRIPTIONOPTIONAL
get_or_createbooleanIf true, if a user with the same ID already exists, it will be returned. Otherwise, the endpoint will return 409 Conflict.

Response object schema

NAMETYPEDESCRIPTIONOPTIONAL
idstringUser ID.
dataobjectUser additional data.
created_atdateWhen the user was created.
updated_atdateWhen the user was last updated.
followers_countnumberNumber of users that follow this user.
following_countnumberNumber of users this user is following.

The following example assumes the user id of "bob".

# the JWT token would be built using a payload similar to:
#{
#    "resource": "users"
#    "action": "write"
#    "feed_id": "*"
#}

curl -i -X POST -d "{\"id\":\"bob\","\"data\":{\"extra\":\"fields\",\"flag\":false}}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/user/?api_key=YOUR_API_KEY"

User detail

The user detail endpoint is located at user/(id)/

Authentication method: Server-Side Authentication

Resource Name: users

Feed ID: *

Authentication method: Client-Side Authentication

The user detail endpoint can be used can be used to retrieve (GET), update (PUT) and delete (DELETE) a user.

GET

Query parameters

NAMETYPEDESCRIPTIONOPTIONAL
with_follow_countsbooleanIf true, the following_count and followers_count will be included in the response.

The returned object schema is described in the user endpoint.

The following example assumes the user id of "bob".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X GET \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/user/bob/?api_key=YOUR_API_KEY"

PUT

Note: You can only change a user's data field.

Request data

NAMETYPEDESCRIPTION
dataobjectUser data field.

The returned object schema is described in the user endpoint.

The following example assumes the user id of "bob".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X PUT -d "{\"data\":{\"modified\":\"fields\",\"modified\":true}}"\
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/user/bob/?api_key=YOUR_API_KEY"

DELETE

Will return an empty response on success.

The following example assumes the user id of "bob".

# the JWT token would be built using a payload similar to:
#{
#    "user_id": "bob"
#}

curl -i -X DELETE \
  -H "Content-Type: application/json" \
  -H "Stream-Auth-Type: jwt" \
  -H "Authorization: TOKEN" \
  "https://APP_REGION-api.stream-io-api.com/api/v1.0/user/bob/?api_key=YOUR_API_KEY"

Advanced

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.

NAMEDESCRIPTION
api_keyThe API key, it can be safely shared with untrusted entities
api_secretThe API secret, it is used to generate the feed tokens
app_idA reference to the application id in Stream. This is only used for realtime notifications
api_versionThe version of the API
For example: v1.0
clientThe client class that manages API calls and authentication
feedAn instance of a feed pointing to a reference of user id and feed slug
feed_slugThe name of the feed group, for instance user, trending, flat etc.
For example: flat
user_idThe owner of the given feed
feed_idThe combination of feed slug and user id separated by a colon
For example: flat:1
tokenThe JWT auth token for a specific feed. It is created by signing the base 64 encoded JWT header and payload with the api_secret
For example: yuXEO2nNOrcwd36sgq8nMC1e2qU
signatureCombination of feed_id (without colon) and the token
For example: flat123 yuXEO2nNOrcwd36sgq8nMC1e2qU
signerThe class responsible for creating tokens
foreign_idThe foreign id of an activity, used in conjunction with a time attribute in an activity, is used to generate a unique reference for updating and deleting activities
locationThe name of the API location
For example: us-east, us-west etc
STREAM_URLThe environment variable containing all details to initialize a client. This is only used for Heroku
For example: https://ahj2ndz7gsan:secret@us-east.stream-io-api.com/?app_id=1