Quick Start

Our Platform API helps you interact with the SendBird servers. The APIs are designed around RESTful principles, and return JSON payloads in response to HTTP requests. The client SDKs handle many of the requests and responses natively. However, utilizing our Platform API can add flexibility and functionality from the server side.

Note: The Platform API is not designed for client side use. Use the corresponding SDKs instead.


Base URL

The base URL used for all APIs is formatted as the following:

https://{region_identifier}.sendbird.com/v3

To get the base url for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and check the App Credentials > API URL.


Headers

A typical request to the Platform API includes the following headers:

Content-Type: application/json, charset=utf8
Api-Token: {API_Token}
  • Content-Type: every request must include a Content-Type header.
  • API Token: an API token is required to identify and authenticate your app. An exception is when you want to perform actions outside of a specific application (such as creating a new application, or fetching a list of all your apps), in which case you must provide Basic Authentication.

If your request contains a file, you must send a Multipart request. Add multipart/form-data to your Content-Type header, as well as a boundary, which is a delimiter string that separates each data field.

Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"

{value}

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"

{value}

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"

{value}

----some_boundary_delimiter_string
Content-Disposition: form-data; name="{key}"; filename="{file_name}"
Content-Type: {Content-Type}

{content}

----some_boundary_delimiter_string--
import os
import requests
api_headers = {'Api-Token': '{api_token}'}
data = {
    'key1': {value},
    'key2': {value}
}
filepath = os.path.join(os.path.dirname(__file__), '{file_path}', '{file_name}')
upload_files = {'file_key': ('{file_name}', open(filepath, 'rb'))}
res = requests.post('{url}', headers=api_headers, data=data, files=upload_files)
curl -X {HTTP Method} 
    -H "Api-Token: {api_token}" 
    -H "Content-Type: multipart/form-data; boundary=--some_boundary_delimiter_string" 
    -F "key1=value" 
    -F "key2=value" 
    -F "file_key=@filename"
    "url"
Python request example
# python: Create User API
import os
import requests
api_headers = {'Api-Token': '{api_token}'}
data = {
    'user_id': 'some_user_id',
    'nickname': 'some_nickname',
    'issue_access_token': True,
}
filepath = os.path.join(os.path.dirname(__file__), '{file_path}', '{file_name}')
upload_files = {'profile_file': ('{file_name}', open(filepath, 'rb'))}
res = requests.post('https://{region_identifier}.sendbird.com/v3/users', 
        headers=api_headers, 
        data=data,
        files=upload_files)

Authentication

To use the Platform API with a specific application, you must authenticate a request using your API token. You can find the token in the dashboard under Overview - App Credentials. The API token in the dashboard is your master API token. The master API token is issued when an application is created, and it cannot be revoked or changed.
With the master API token, you can issue an API token, revoke other API tokens, or retrieve a list of issued API tokens. As stated above, an API token must be included in your HTTP Request Header for authentication.

Note: This has been changed from our previous Server API, where the token had to be included in the payload.

Request Header
"Api-Token": {API_Token}

DO NOT request any Platform API from your client application. If your API token information is compromised, you risk losing all your data.

Authenticate with HTTP Basic Authentication when you want to delete or list all applications, or create one. In these scenarios, you can authenticate your request with your login details instead of your API tokens. Generate a Basic Auth Header by inputting your login email and password.

If you create a Basic Auth header manually, then do the following:

  1. Combine your email and password with a single colon (:). For example, api@sendbird.com:1234
  2. Encode the resulting string using the RFC2045-MIME variant of Base64, no more than 76 characters per line. For example, type echo 'api@sendbird.com:1234' | base64 on the command line to encode.
  3. Prepend the authorization method Basic and a space to the encoded string, which is used as a value for an Authorization field. For example, Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0Cg==
  4. Assign the resulting authorization information to the Authorization field in your HTTP header. For example, Authorization: Basic YXBpQHNlbmRiaXJkLmNvbToxMjM0Cg==

URL Encoding

When sending requests over HTTP, you should encode your URLs into a browser-readable format. urlencoding replaces unsafe non-ASCII characters with a % followed by hex digits to ensure readability.

In the following, user_id is urlencoded. For example, user_id@email.com is urlencoded to user_id%40email.com.

GET https://{region_identifier}.sendbird.com/v3/users/{user_id}

Note: If you want region_identifier for your app, sign in to the SendBird Dashboard, select the application, open the Overview, and see the App Credentials > API URL.

Like the following, you can encode URLs in most languages.

encodeURIComponent("api@sendbird.com");
import urllib
urllib.quote('api@sendbird.com', safe='')

which returns:

api%40sendbird.com

Therefore, your full request looks like:

GET https://{region_identifier}.sendbird.com/v3/users/api%40sendbird.com