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.

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.

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:

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!

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
• Client-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:

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

// 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"

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

# 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"

# 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"

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.

  # 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

Query parameters

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"

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.

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.

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"

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

Query parameters

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:

# 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.

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

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"

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

# 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`"

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

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}`}"

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.

# 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.

# 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"

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

DELETE

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 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"

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

# 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"

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.

# 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`"

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

POST

Request 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 reaction with the same ID already exists, the request will error with code 409 Conflict.

Returned reaction object schema

# 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"

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

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

# 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"

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

GET

URI parameters

Query parameters

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

# 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"

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

Response object

OG Image object

OG Video object

OG Audio object

# 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"

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

POST

Request 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

# 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"

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

The returned object schema is described in the collection endpoint.

# 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 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"

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

Returned object schema

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

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

Will return an empty response on success.

# 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"

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

POST

Request data

Returned object schema

# 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

Will return an empty response on success.

# 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"

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

GET

Query parameters

Returned object schema

POST

Request data

Returned object schema

# 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

Will return an empty response on success.

# 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"

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

POST

Request data

Query parameters

Response object schema

# 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"

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

GET

Query parameters

The returned object schema is described in the user endpoint.

# 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

The returned object schema is described in the user endpoint.

# 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 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"

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.

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.

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.