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, 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 Chat 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.

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

3. Browse Documentation

This documentation page includes all API endpoints and describes the three authentication available to use Stream Chat.

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

Basics

Base API URL:
https://chat-us-east-1.stream-io-api.com

Common Parameters

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

Name Type Description
api_key string The API Key

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

Compression

Stream API supports gzip and deflate compression, make sure that your client negotiate compression.
Enabling compression can reduce significantly latency and used bandwidth and it's highly recommended.

JSON

Unless specified differently, all POST data must be JSON encoded and all responses are also JSON encoded.

Authentication

API Keys and Tokens

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.

If you are not familiar with JWT we highly recommend reading more about it here

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.

Server-Side Authentication

Requests from a back-end application to Stream Chat API should 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 not include any claim beside claims defined by JWT specifications (ie. "iat", "exp", ...).

⚠️ When using server-side authentication; there will be no permission checking and you will be able to perform any valid request for any of your user. You should never share a server-side token with any untrusted party or use it directly on the mobile or web-browser. If your API secret or server-side token gets compromised you should create a new API Key from the dashboard and delete the one that got compromised.

Some endpoints can only used with server-side auth; ie. changing the configuration of your application or perform other actions such as changing users' role.

Token example

Here is the server-side token for a fictional application with API Secret "top-secret":

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.-hJRcjmUOcS0P-Pllpe8gnOtMINmm7Ktebd3eKUroAc

Client-Side Authentication

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

JWT usage for client-side authentication

When using client-side auth, you generate different token to each of your user and include their string ID in the user_id claim.

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.

For security reasons, some API endpoints and some specific actions can be performed only server-side.

User tokens will effectively authenticate the user based on the user_id claim. After that all API calls will be checked for permissions.
More information about permissions is available on Chat documentation.

Token example

Here is the user token for user "jack" on a fictional application with API Secret "top-secret":

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiamFjayJ9.pO3Fa8TJnPXsl62-XHK94S8hFk6dUz_2Q9au6H5xBSQ

Anonymous Authentication

Anonymous authentication allows you to use a sub-set of Chat's API without generating a user token.

Anonymous authentication works exactly as client-side auth with a couple of exceptions:

  • You must not send the Authorization header
  • You must send the stream-auth-type header set to anonymous

For security reasons, only a small subset of the API endpoints will be available to anonymous users.

Websocket

Stream Chat uses Websocket connections to propagate chat events to all connected clients in real-time. Websockets are only used by Chat API servers to push events to users, you do not need them server-side.

Your Chat application should create a websocket connection per each user and wait until such connection is established before doing any other API call.

Websocket and authentication

Websocket connections must include authentication information; since it is not possible to send HTTP headers or a request body; such information must be included as query parameters.

Websocket and user data

Websocket connection must include the full information for the current user as well; the API endpoint will ensure that such user exists and will update it if necessary.

GET
Websocket Connect
Creates a websocket connection for a chat user
/connect

QUERY PARAMETERS

Name Description
id

string

the ID for the user (must match JWT's user_id claim)

... additional fields

any type

additional fields

Websocket hello event

When the websocket connection is created with valid credentials and user payload; you will receive an event which includes fundamental information for later user of chat.
Such message includes:

  • Current user's information including unread counts, the list of muted users and banned status
  • The connection_id for this session; you should store this, some API endpoints requires this parameter to be provided

{ "connection_id":"e71fd066-7e95-46db-b36a-33ea87cb9653", "cid":"*", "type":"health.check", "me":{ "id":"fancy-base-6", "role":"user", "created_at":"2019-11-05T21:35:24.395023Z", "updated_at":"2019-11-05T21:35:24.398655Z", "last_active":"2019-11-05T21:35:24.397995Z", "online":true, "invisible":false, "devices":[ ], "mutes":[ ], "unread_count":0, "total_unread_count":0, "unread_channels":0, "name":"Fancy base", "image":"https://getstream.io/random_svg/?name=Fancy+base" }, "created_at":"2019-11-05T21:35:24.403589987Z" }

Websocket health-check events

After the websocket connection is correctly established, the client will receive health-checks messages periodically.
Your Chat client should make sure that such health-check event is received not later than 30 seconds ago; if that's not the case you should close and retry connecting.

[{ "type":"health.check", "client_id":"fancy-base-6--0fd2eb3f-f20e-4182-820a-590b380b884f", "user_id":"fancy-base-6" }]

Websocket and retries

Unlike REST API calls, websocket connections are long-lived and might get closed due to internet connection errors.
The recommended approach is to monitor internet connection, websocket close and error events and always retry to connect when a network issue causes the connection to break.

Websocket and precondition errors

If you provide invalid authentication information or invalid data payload, an error message will be sent to the client and the connection will be closed with a status 1000 Normal Closure immediately after.
You can inspect the error message to gather more information about the failure and use that to decide what to do next. Error messages are JSON encoded and have the same schema as the ones from REST API endpoints.
When the connection is closed with such status you should not blindly retry to create the connection as it will almost certainly fail again with the same error.

{ "error":{ "code":43, "message":"JWTAuth error: signature is not valid. Make sure the token is created using the secret for API key \"rl5oo8sqdo85\"", "StatusCode":401, "duration":"" } }

Websocket events

Once the websocket is created, you can move on and subscribe the user to channels either by using the Query Channels API endpoint or the Get Or Create Channel.
From that point on, you will receive events related to all channels the user is watching (ie. messages from other users, typing events, mark read events, ...).

Websocket notification events

You should expect the websocket connection to receive events that are not related to channels that the user is watching with the current websocket connection.

Get Application

GET
Get Application
Returns all configurations for one Stream Chat Application
/app

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

RESPONSES

200 (click to expand)
Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

allowed values: all fun_set moderation_set giphy imgur flag unban ban mute unmute

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

disable_auth_checks

boolean

disable_permissions_checks

boolean

name

string

organization

string

... additional fields

any type

additional fields

auth_type

string

bundle_id

string

development

boolean

enabled

boolean

host

string

key_id

string

notification_template

string

team_id

string

data_template

string

enabled

boolean

notification_template

string

suspended

boolean

suspended_explanation

string

webhook_url

string

duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Update Application

PATCH
Update Application
Allows changing the application's configuration
/app

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
auth_key

string

auth_type

string

allowed values: certificate token

bundle_id

string

development

boolean

host

string

keep_devices

boolean

key_id

string

notification_template

string

p12_cert

string

team_id

string

disable_auth_checks

boolean

disable_permissions_checks

boolean

data_template

string

keep_devices

boolean

notification_template

string

server_key

string

webhook_url

string

QUERY PARAMETERS

RESPONSES

200 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

List Channel Types

GET
List Channel Types
Returns the list of all channel types for the app
/channeltypes

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

RESPONSES

200 (click to expand)
Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

action

string

allowed values: Deny Allow

name

string

owner

boolean

priority

integer

>=1

<=999

resources

array of string

>=1

roles

array of string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Create Channel Type

POST
Create Channel Type
Creates a new channel type
/channeltypes

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

client_id

string

the ID of the client, only needed client-side

commands

array of string

allowed values: all fun_set moderation_set giphy imgur flag ban mute

connect_events

boolean

connection_id

string

the ID of the connection, only needed client-side

max_message_length

integer

message_retention

string

mutes

boolean

name

string

action

string

allowed values: Deny Allow

name

string

owner

boolean

priority

integer

>=1

<=999

resources

array of string

>=1

roles

array of string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

uploads

boolean

url_enrichment

boolean

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

allowed values: all fun_set moderation_set giphy imgur flag unban ban mute unmute

connect_events

boolean

created_at

string

duration

string

request duration

max_message_length

integer

message_retention

string

mutes

boolean

name

string

action

string

allowed values: Deny Allow

name

string

owner

boolean

priority

integer

>=1

<=999

resources

array of string

>=1

roles

array of string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Delete Channel Type

DELETE
Delete Channel Type
Deletes a channel type
/channeltypes/{name}

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

RESPONSES

200 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Update a channel type

PUT
Update a channel type
Allows you to change permissions and configurations for a channel type. Changes will be reflected to all channels of this type.
/channeltypes/{name}

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

client_id

string

the ID of the client, only needed client-side

commands

array of string

allowed values: all fun_set moderation_set giphy imgur flag unban ban mute unmute

connect_events

boolean

connection_id

string

the ID of the connection, only needed client-side

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

action

string

allowed values: Deny Allow

name

string

owner

boolean

priority

integer

>=1

<=999

resources

array of string

>=1

roles

array of string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

allowed values: all fun_set moderation_set giphy imgur flag unban ban mute unmute

connect_events

boolean

created_at

string

duration

string

request duration

max_message_length

integer

message_retention

string

mutes

boolean

name

string

action

string

allowed values: Deny Allow

name

string

owner

boolean

priority

integer

>=1

<=999

resources

array of string

>=1

roles

array of string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Get Channel Type

GET
Get Channel Type
Returns the information about one channel type
/channeltypes/{type}

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

RESPONSES

200 (click to expand)
Name Description
automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

duration

string

request duration

max_message_length

integer

message_retention

string

mutes

boolean

name

string

action

string

allowed values: Deny Allow

name

string

owner

boolean

priority

integer

>=1

<=999

resources

array of string

>=1

roles

array of string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Check Push

POST
Check Push
Allows you to test your Push notification settings for APN and Firebase.
/check_push

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
apn_template

string

client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

firebase_data_template

string

firebase_template

string

message_id

string

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
error_message

string

provider

string

duration

string

request duration

general_errors

array of string

rendered_apn_template

string

rendered_firebase_template

string

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Query Channels

GET
Query Channels
Returns channels that match a provided query, supports pagination **Note** when using user authentication, only the channels that the user has the permission to read will be returned.
/channels

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

... additional fields

any type

additional fields

... additional fields

any type

additional fields

limit

integer

message_limit

integer

how many messages should be included to each channel

offset

integer

presence

boolean

recovery

boolean

direction

integer

sort direction

field

string

field used to sort

state

boolean

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

watch

boolean

let current user watch returned channels

RESPONSES

200 (click to expand)
Name Description
cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

the time the channel was created

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

last_message_at

string

the last time a message was added, null for empty channels

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

the last time the channel was updated

... additional fields

any type

additional fields

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

command

string

created_at

string

deleted_at

string

html

string

id

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

parent_id

string

... additional fields

any type

additional fields

reply_count

integer

show_in_channel

boolean

text

string

type

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

last_read

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

watcher_count

integer

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Deletes a channel

DELETE
Deletes a channel
Delete Channel
/channels/{type}/{id}

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

RESPONSES

200 (click to expand)
Name Description
cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

the time the channel was created

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

last_message_at

string

the last time a message was added, null for empty channels

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

the last time the channel was updated

... additional fields

any type

additional fields

duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Update Channel

POST
Update Channel
Allows you to update data, members and invites for a channel
/channels/{type}/{id}

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
accept_invite

boolean

add_members

array of string

<=100

add_moderators

array of string

<=100

client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

created_by_id

string

frozen

boolean

invites

array of string

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

... additional fields

any type

additional fields

demote_moderators

array of string

<=100

invites

array of string

<=100

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

html

string

the HTML version of the message (only allowed server-side)

id

string

<=255

mentioned_users

array of string

<=25

parent_id

string

the ID of the parent message

show_in_channel

boolean

text

string

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

... additional fields

any type

additional fields

reject_invite

boolean

remove_members

array of string

<=100

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

the time the channel was created

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

last_message_at

string

the last time a message was added, null for empty channels

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

the last time the channel was updated

... additional fields

any type

additional fields

duration

string

request duration

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

command

string

created_at

string

deleted_at

string

html

string

id

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

parent_id

string

... additional fields

any type

additional fields

reply_count

integer

show_in_channel

boolean

text

string

type

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

... additional fields

any type

additional fields

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Hide Channel

POST
Hide Channel
Hides a channel for a user until a new message is added
/channels/{type}/{id}/hide

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Get or Create Channel

POST
Get or Create Channel
Gets or create a channel by type and ID
/channels/{type}/{id}/query

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

created_by_id

string

frozen

boolean

invites

array of string

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

... additional fields

any type

additional fields

id_gt

integer

id_gte

integer

id_lt

integer

id_lte

integer

limit

integer

offset

integer

id_gt

string

id_gte

string

id_lt

string

id_lte

string

limit

integer

offset

integer

presence

boolean

state

boolean

watch

boolean

let current user watch returned channels

id_gt

integer

id_gte

integer

id_lt

integer

id_lte

integer

limit

integer

offset

integer

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

the time the channel was created

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

last_message_at

string

the last time a message was added, null for empty channels

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

the last time the channel was updated

... additional fields

any type

additional fields

duration

string

request duration

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

command

string

created_at

string

deleted_at

string

html

string

id

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

parent_id

string

... additional fields

any type

additional fields

reply_count

integer

show_in_channel

boolean

text

string

type

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

last_read

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

watcher_count

integer

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Show Channel

POST
Show Channel
Shows a previously hidden channel
/channels/{type}/{id}/show

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Stop Watching Channel

POST
Stop Watching Channel
Stops watching a channel
/channels/{type}/{id}/stop-watching

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Truncate Channel

POST
Truncate Channel
Removes all messages from a channel
/channels/{type}/{id}/truncate

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

allowed values: all fun_set moderation_set giphy imgur flag unban ban mute unmute

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

invites

array of string

last_message_at

string

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

... additional fields

any type

additional fields

duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Mark All Read

POST
Mark All Read
Marks all channels as read for one user
/channels/read

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Send Event

POST
Send Event
Send a channel event; the event must be supported by the channel type or it will be discarded with an error
/channels/{type}/{id}/event

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

type

integer

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

... additional fields

any type

additional fields

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

the time the channel was created

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

last_message_at

string

the last time a message was added, null for empty channels

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

the last time the channel was updated

... additional fields

any type

additional fields

cid

string

connection_id

string

created_at

string

banned

boolean

created_at

string

deactivated_at

string

deleted_at

string

created_at

string

id

string

push_provider

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

id

string

invisible

boolean

last_active

string

created_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

online

boolean

role

string

total_unread_count

integer

unread_channels

integer

unread_count

integer

updated_at

string

... additional fields

any type

additional fields

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

command

string

created_at

string

deleted_at

string

html

string

id

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

parent_id

string

... additional fields

any type

additional fields

reply_count

integer

show_in_channel

boolean

text

string

type

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

... additional fields

any type

additional fields

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

... additional fields

any type

additional fields

type

integer

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

watcher_count

integer

... additional fields

any type

additional fields

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Delete File

DELETE
Delete File
Deletes a previously uploaded file
/channels/{type}/{id}/file

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

Name Description
url

string

RESPONSES

200 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Upload File

POST
Upload File
Uploads a file to Stream's CDN
/channels/{type}/{id}/file

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
file

string

the file uploaded

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

file

string

the url of the uploaded file

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Delete Image

DELETE
Delete Image
Deletes a previously uploaded image
/channels/{type}/{id}/image

PATH PARAMETERS

REQUEST BODY SCHEMA

QUERY PARAMETERS

Name Description
url

string

RESPONSES

200 (click to expand)
Name Description
duration

string

request duration

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Upload Image

POST
Upload Image
Uploads an image to Stream's CDN
/channels/{type}/{id}/image

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
file

string

the file uploaded

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

file

string

the url of the uploaded file

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Send Message

POST
Send Message
Sends a message from a user to a channel. - Messages can contain any number custom fields. - Messages larger than 5KB or with more character than allowed by the channel type MaxMessageLength setting will be discarded with an error - Messages sent to a frozen channel will be discarded with an error - The text field of a message will be parsed using Markdown; the resulting HTML is included in the "html" field of the message - URLs included in the message will be scraped and the information retrieved included in the response as attachments
/channels/{type}/{id}/message

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

html

string

the HTML version of the message (only allowed server-side)

id

string

<=255

mentioned_users

array of string

<=25

parent_id

string

the ID of the parent message

show_in_channel

boolean

text

string

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

... additional fields

any type

additional fields

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

name

string

style

string

text

string

type

string

value

string

asset_url

string

author_icon

string

author_link

string

author_name

string

color

string

fallback

string

short

boolean

title

string

value

string

footer

string

footer_icon

string

image_url

string

og_scrape_url

string

pretext

string

text

string

thumb_url

string

title

string

title_link

string

type

string

command

string

created_at

string

deleted_at

string

html

string

id

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

created_at

string

message_id

string

type

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

parent_id

string

... additional fields

any type

additional fields

reply_count

integer

show_in_channel

boolean

text

string

type

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

... additional fields

any type

additional fields

500 (click to expand)
Name Description
code

integer

error code

duration

string

... additional fields

any type

additional fields

message

string

Mark Read

POST
Mark Read
Marks a channel as read for a user. When `message_id` is provided, marks all messages up to that message as read
/channels/{type}/{id}/read

PATH PARAMETERS

REQUEST BODY SCHEMA

Name Description
client_id

string

the ID of the client, only needed client-side

connection_id

string

the ID of the connection, only needed client-side

message_id

string

id

string

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

... additional fields

any type

additional fields

user_id

string

QUERY PARAMETERS

RESPONSES

201 (click to expand)
Name Description
duration

string

request duration

cid

string

automod

string

allowed values: disabled simple AI

automod_behavior

string

allowed values: flag block

commands

array of string

connect_events

boolean

created_at

string

max_message_length

integer

message_retention

string

mutes

boolean

name

string

reactions

boolean

read_events

boolean

replies

boolean

search

boolean

typing_events

boolean

updated_at

string

uploads

boolean

url_enrichment

boolean

created_at

string

the time the channel was created

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

deleted_at

string

frozen

boolean

id

string

last_message_at

string

the last time a message was added, null for empty channels

member_count

integer

created_at

string

invite_accepted_at

string

invite_rejected_at

string

invited

boolean

is_moderator

boolean

role

string

updated_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

type

string

updated_at

string

the last time the channel was updated

... additional fields

any type

additional fields

cid

string

connection_id

string

created_at

string

banned

boolean

created_at

string

deactivated_at

string

deleted_at

string

created_at

string

id

string

push_provider

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

user_id

string

id

string

invisible

boolean

last_active

string

created_at

string

created_at

string

deactivated_at

string

deleted_at

string

id

string

last_active

string

online

boolean

role

string

the user role, can only be set using server-side auth

allowed values: user admin guest

updated_at

string

... additional fields

any type

additional fields

updated_at

string

created_at

string

deactivated_at

string

deleted_at