# Upload

To initiate a file upload you need to execute a **POST** request against the **/libraries/:id/files** endpoint.

Two fields are available in the JSON body of the **POST** request:

* **name** - the name of the file. Required.
* **folder\_id** - the id of the parent folder.\
  Omit this field if the file is attached to the root of the library and not to a parent folder.

In the response you will receive a time-limited **JWT token** (expires in 15 minutes) and a **target URL** where you can upload the actual file bytes to.

#### 1. Request to retrieve a token for upload and storage server URL

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```bash
curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/libraries/8606721f-d847-4721-a5dc-6537e822104c/files \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"name": "prom.jpg"}'
```

{% endcode %}
{% 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());

//Put your library id here - this value is just an example
final String libraryId = "8606721f-d847-4721-a5dc-6537e822104c";
		
Map<String, String> data = Map.of(
       "name", "Birthday Party"
);
String jsonData = new ObjectMapper().writeValueAsString(data);

HttpRequest request = HttpRequest.newBuilder()
  .POST(HttpRequest.BodyPublishers.ofString(jsonData))
  .uri(new URI("https://api.digitalsamba.com/api/v1/libraries/" + libraryId + "/folders"))
  .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
{
    "file_id": "0b20a544-d2d7-4c1b-b651-dc132a76a756",
    --This is the internal file name (not visible to end users inside the room)
    "file_name": "Kn3H49JwJogc6ujAgnTtkN9ImWKVmYYebrk3yQWW.jpg",
    --URL to execute a POST request to upload the file bytes to
    "external_storage_url": "https://.............",
    --Time limited JWT token to authenticate to the external storage URL
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJuYW1lIjoiS24zSDQ5SndKb2djNnVqQWduVHRrTjlJbVdLVm1ZWWVicmszeVFXVy5qcGciLCJhY3Rpb24iOiJ1cGxvYWQiLCJ0eXBlIjoibGlicmFyeSIsImxpYnJhcnlfaWQiOiI4NjA2NzIxZi1kODQ3LTQ3MjEtYTVkYy02NTM3ZTgyMjEwNGMiLCJmaWxlX2lkIjoiMGIyMGE1NDQtZDJkNy00YzFiLWI2NTEtZGMxMzJhNzZhNzU2IiwiaXNzIjoibGFyYXZlbCIsImlhdCI6MTcyODQ3NzIzMiwiZXhwIjoxNzI4NDc4MTMyfQ.QW90_-9OtXwCyL2vcAtm7oz5UJGuvdKMi4Ykjan8pN8",
    --Unix timestamp when the JWT token expires and is no longer valid (in 15 minutes)    
    "expiration_timestamp": 1728478132
}
```

#### 2. Request to finish the upload

{% hint style="warning" %}
The POST request URL is the **external\_storage\_url** from the previous request.

You need to put the token from the first request into the **Authorization: Bearer** header.

The file is sent in a multipart request where the field name is "**file**".
{% endhint %}

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```bash
curl --request POST \
  --header "Authorization: Bearer eyJ0eXAiOiJKV1QiL............." \
  -F "file=@prom.jpg"
  --url external_storage_url \
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Response (200 OK)

```json
{
    "message": "File has been uploaded",
    "file": "Kn3H49JwJogc6ujAgnTtkN9ImWKVmYYebrk3yQWW.jpg",
    "size": 1311689,
    "success": true
}
```