# Create

To create a new room you need to execute a **POST** request against the **/rooms** endpoint.

The only required field is the **privacy** field, which accepts "**public**" and "**private**" values.

**Public** rooms can be accessed by everyone who knows the room URL. They are easy to start with and you can invite people by giving them the room URL.

**Private** rooms on the other hand can be accessed only by having a valid [Token](https://docs.digitalsamba.com/reference/rest-api/tokens). They are generally more secure, because even if you know the room URL, you cannot enter inside without having a valid issued token.

{% hint style="success" %}
To enable end-to-end encryption (e2ee) use the **e2ee\_enabled** flag when creating or editing the room.
{% endhint %}

If you are doing moderated meetings or webinars you would want to specify the [roles](#3.-request-a-room-with-moderator-speaker-and-attendee-roles) field. \
By default you are provided with three roles in your team - **moderator**, **speaker** and **attendee** which should be enough for most needs. Also if there is more than one role in your room, you must specify the **default\_role** field. About roles/permissions details -> read [here](https://docs.digitalsamba.com/reference/rest-api/roles-and-permissions).

{% hint style="success" %}
There are a lot more room fields you can configure. For a full list -> read [here](https://developer.digitalsamba.com/rest-api/#rooms-POSTapi-v1-rooms).
{% endhint %}

{% hint style="info" %}
If you don't provide a **friendly\_url** in the request, then the API will auto-generate one.
{% endhint %}

#### 1. Request (will auto-generate room URL)

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

```bash
curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"privacy": "public"}'
```

{% endtab %}

{% tab title="Java" %}

```java
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

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

Map<String, String> data = Map.of("privacy", "public");
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .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 %}

#### Response (200 OK)

```json
{
  "id": "c39d7c40-7ff7-4faa-b06f-698a639a9523",
  "friendly_url": "l5zIyafmlEFMPKA",
  "privacy": "public",
  ....................
}
```

As you can see a **friendly\_url** was auto-generated and the public room will be accessible at \ <mark style="color:blue;">https\://</mark><mark style="color:blue;">**teamNameHere**</mark><mark style="color:blue;">.digitalsamba.com/</mark><mark style="color:blue;">**l5zIyafmlEFMPKA**</mark>

#### 2. Request (will use the friendly\_url you provided)

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

```bash
curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"privacy": "public", "friendly_url": "my-test-meeting"}'
```

{% endtab %}

{% tab title="Java" %}

```java
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

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

Map<String, String> data = Map.of(
  "privacy", "public",
  "friendly_url", "my-test-meeting"
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .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 %}

#### Response (200 OK)

```json
{
  "id": "c39d7c40-7ff7-4faa-b06f-698a639a9523",
  "friendly_url": "my-test-meeting",
  "privacy": "public",
  ....................
}
```

The newly created meeting will be available at the url you specified:\ <mark style="color:blue;">https\://</mark><mark style="color:blue;">**teamNameHere**</mark><mark style="color:blue;">.digitalsamba.com/</mark><mark style="color:blue;">**my-test-meeting**</mark>

#### 3. Request (a room with moderator, speaker and attendee roles)

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

```bash
curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
     "privacy": "public", 
     "roles": ["moderator", "speaker", "attendee"], 
     "default_role": "attendee"
  }'
```

{% endtab %}

{% tab title="Java" %}

```java
import com.fasterxml.jackson.databind.ObjectMapper;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.util.Base64;
import java.util.Map;

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

Map<String, Object> data = Map.of(
  "privacy", "public",
  "roles", new String[] {"moderator", "speaker", "attendee"},
  "default_role", "attendee"
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/rooms"))
  .header("Authorization", authorizationHeader)
  .header("Content-Type", "application/json")
  .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 %}

Note how the **default\_role** needs to be specified when there is more than one role in the room.\
The default role is the role being used if a participant visits the public room without a token, or there is no role specified in the token. In general the least powerful role should be the default one, because you should not want participants to enter by default as moderators.

#### Response (200 OK)

```json
{
  "id": "c39d7c40-7ff7-4faa-b06f-698a639a9523",
  "friendly_url": "l5zIyafmlEFMPKA",
  "privacy": "public",
  "roles": [
        {
            "id": "76bb6199-2900-4b8d-b1bf-351dec4a8db4",
            "name": "moderator",
            "display_name": "Moderators"
        },
        {
            "id": "e5bad6b9-48bd-46a0-9482-af78a834c28c",
            "name": "speaker",
            "display_name": "Speakers"
        },
        {
            "id": "8cae6c49-c40a-4965-a32b-6cf20de36755",
            "name": "attendee",
            "display_name": "Attendees"
        }
  ],
  "default_role": {
      "id": "8cae6c49-c40a-4965-a32b-6cf20de36755",
      "name": "attendee",
      "display_name": "Attendees"
  },
  ....................
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalsamba.com/reference/rest-api/rooms/create.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.