# 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
}
```


---

# 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/content-library/files/upload.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.