# Create

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

The following fields need to be set:

* **name ->** internal <mark style="color:red;">**unique**</mark> name to reference the role in [rooms](/reference/rest-api/rooms.md) and [tokens](/reference/rest-api/tokens.md)
* **display\_name ->** the display name people will see visually inside the participants list
* **permissions ->** a JSON object of the [permission names](/reference/rest-api/roles-and-permissions/permissions.md) this role is allowed to have. Allowed permissions have **true** as a value. For role sensitive permissions like **remote\_muting** you can additionally specify an array with the role names which the participant is allowed to operate on.\
  For example you can make a Speaker be allowed to remote mute an Attendee, but not remote mute a Moderator. If you don't specify the array (and just put **true**), that means the participant is allowed to operate on all roles (current and future). That gives you full flexibility.
* **description** (optional) -> text description if you want to add some explanations

{% hint style="warning" %}
Creating a role doesn't immediately assign it to any rooms. You need to specify the available roles inside a room during [room creation](https://docs.digitalsamba.com/reference/rest-api/roles-and-permissions/pages/vMyCO7Q10NmBeuALwo2P#3.-request-a-room-with-moderator-speaker-and-attendee-roles). If all of your rooms will have the same roles it may be easier for you to set these roles in the default [team settings](/reference/rest-api/default-room-settings.md), so all rooms will inherit the same default roles.
{% endhint %}

#### Request

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

```bash
curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/roles \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
     "name": "custom", 
     "display_name": "Custom", 
     "permissions": {
        "start_session": true, 
        "remote_muting": ["speaker", "attendee"],
        "raise_hand": true
     } 
  }'
```

{% 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(
  "name", "custom",
  "display_name", "Custom",
  "permissions", Map.of( "start_session", true,
		         "remote_muting", new String[] {"speaker", "attendee"},
		         "raise_hand", true
		 )
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/roles"))
  .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": "2d9448b9-d9ee-4102-b31a-f83ab4af2af8",
    "name": "custom",
    "display_name": "Custom",
    "description": null,
    "default": false,
    "created_at": "2023-03-24T13:32:05Z",
    "updated_at": "2023-03-27T13:46:22Z",
    "permissions": {
        "ask_remote_unmute": false,
        "broadcast": false,
        "end_session": false,
        "general_chat": false,
        "manage_broadcast": false,
        "manage_roles": false,
        "manage_screenshare": false,
        "raise_hand": true,
        "recording": false,
        "remote_muting": [
            "speaker",
            "attendee"
        ],
        "remove_participant": false,
        "screenshare": false,
        "start_session": true
    }
}
```


---

# 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/roles-and-permissions/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.