# REST API

The **base** URL of the HTTP REST API is located at <https://api.digitalsamba.com/api/v1>

To access a concrete resource -> append it to the **base** URL - e.g. to access [rooms](https://docs.digitalsamba.com/reference/rest-api/rooms) use: <https://api.digitalsamba.com/api/v1/rooms>

{% hint style="info" %}
You need to [authenticate](https://developer.digitalsamba.com/rest-api/#authenticating-requests) to the API by providing your **Developer key** in a standard HTTP "**Authorization: Bearer {DEVELOPER\_KEY}**" header. Alternatively you can use HTTP Basic Authentication and provide your **Team ID** as username and **Developer key** as password. <br>

You can find your **Team ID** and **Developer key** in the [dashboard](https://dashboard.digitalsamba.com/team) after you sign up to Digital Samba Embedded.
{% endhint %}

{% hint style="warning" %}
The API is rate limited to a maximum of 1000 requests per minute. Read more [here](https://docs.digitalsamba.com/reference/rest-api/rate-limiting).
{% endhint %}

### Authentication example

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY
```

{% endtab %}

{% tab title="Java" %}

```java
String TEAM_ID = "YOUR_TEAM_ID";
String DEVELOPER_KEY = "YOUR_DEVELOPER_KEY";
String authorizationHeader = "Bearer " + Base64.getEncoder().encodeToString((TEAM_ID + ":" + DEVELOPER_KEY).getBytes());

HttpRequest request = HttpRequest.newBuilder()
  .GET()
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .build();

HttpClient client = HttpClient.newHttpClient();
HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

System.out.println("Status code: " + response.statusCode());
System.out.println("Body: " + response.body());
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
This REST API uses the following common conventions:

1. For listing (retrieval) -> use the **GET** verb
2. For creation -> use the **POST** verb
3. For editing -> use the **PATCH** verb
4. For deletion -> use the **DELETE** verb
   {% endhint %}

### Pagination

Most of the retrieval endpoints (**GET** verb) support pagination. The reason for that is you could have created tens of thousands of rooms or recordings and it is not practical to list all of them in a single request/response. It would put a significant strain on the bandwidth. Please read the [Pagination](https://docs.digitalsamba.com/reference/rest-api/pagination) section for more details.

### Default room settings

Your team is created when you sign up to Digital Samba Embedded. There are default room settings which all rooms inherit by default. All of your rooms are hosted under your chosen team name -> https\://**teamNameHere**.digitalsamba.com/my-room\
Read the [Default room settings](https://docs.digitalsamba.com/reference/rest-api/default-room-settings) section for more details.

### Rooms

Room is where the video conference takes place.

Before embedding a room in your application, you must first create/configure the room.\
You need to set the URL of the room, what roles are available inside the room, the available features to the users, etc... Read the [Rooms](https://docs.digitalsamba.com/reference/rest-api/rooms) section for more details.

### Live statistics

You can find out which rooms are currently live (have participants inside).  You can also query for the live participants in a concrete room. Read more [here](https://docs.digitalsamba.com/reference/rest-api/live-usage).

### Recordings

Any video conference can be recorded by simply clicking the record button on the toolbar or calling the [startRecording](https://docs.digitalsamba.com/reference/sdk/methods/startrecording) SDK method. An **mp4** file will be produced and it will be accessible through the dashboard or the [download](https://docs.digitalsamba.com/reference/rest-api/recordings/download) API endpoint. Read the [Recordings](https://docs.digitalsamba.com/reference/rest-api/recordings) section for details.

### Webhooks

Webhooks are a way to integrate your existing backend with different room events.&#x20;

For example if a user joins or leaves the session, you may want your backend to be informed of these events with a callback HTTP request.

Read the [Webhooks](https://docs.digitalsamba.com/reference/rest-api/webhooks) section for more details.

{% hint style="info" %}
Have a look also at our [Scribe / Postman](https://developer.digitalsamba.com/rest-api) docs.
{% endhint %}