# List

To list the existing libraries you need to execute a **GET** request against the **/libraries** endpoint. 

Since potentially there could be thousands of libraries, pagination is supported with **limit**, **order** and **after** arguments. Read about [pagination](https://docs.digitalsamba.com/reference/rest-api/pagination) to learn the details of it. By default maximum 100 libraries will be returned in the response.

{% hint style="info" %}
If you want to retrieve the details of one concrete library execute a **GET** request against the **/libraries/:id** endpoint
{% endhint %}

#### Request (listing all libraries)

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

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

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

HttpRequest request = HttpRequest.newBuilder()
  .GET()
  .uri(new URI("https://api.digitalsamba.com/api/v1/libraries"))
  .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 %}

#### Response (200 OK)

```json
{
    "total_count": 6124,
    "data": [
        {
            "id": "a31d02af-aa30-45be-9202-300909c41280",
            "external_id": null,
            "name": "Library 05.09.2024 14:00",
            "source": "api",
            "created_at": "2024-09-05T14:00:34Z"
        },
        ...............99 more libraries...............
    ]
} 
```

{% hint style="info" %}
The **total\_count** is the total amount of libraries you have globally. It is **NOT** the amount of libraries in the current page returned in the **data** array. In the above example you have 6124 libraries in total, but in the data array there will be maximum 100 libraries (the default limit argument value).
{% endhint %}

#### Request (get a concrete library)

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

```bash
curl --request GET \
  --url https://api.digitalsamba.com/api/v1/libraries/ec463c74-b227-4bec-9c95-b3eb515b6548 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY
```

{% 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
String libraryId = "ec463c74-b227-4bec-9c95-b3eb515b6548";

HttpRequest request = HttpRequest.newBuilder()
  .GET()
  .uri(new URI("https://api.digitalsamba.com/api/v1/libraries/" + libraryId))
  .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 %}

#### Response (200 OK)

```json
{
    "id": "ec463c74-b227-4bec-9c95-b3eb515b6548",
    "external_id": null,
    "name": "Holiday in Greece",
    "source": "api",
    "created_at": "2024-10-07T11:32:56Z",
    "files": [
        {
            "id": "5fa70307-e4eb-4819-b9f2-38985cbe9b9f",
            "name": "starship.png",
            "type": "image",
            "size": 839030,
            "source": "api",
            "status": "completed",
            "created_at": "2024-10-14T11:44:43Z"
        },
        ................
    ],
    "folders": [
        {
            "id": "e6a08bd6-7262-4fa2-8adf-1f7ddefe6907",
            "name": "Holiday",
            "source": "api",
            "created_at": "2024-10-14T10:16:24Z"
        },
        ................
    ]
} 
```

{% hint style="warning" %}
Only files and folders in the root of the library are returned in this endpoint.\
If you would like to retrieve the whole hierarchy of folders and files in them, then call the **/libraries/:id/hierarchy** endpoint as shown below.
{% endhint %}

#### Request (complete hierarchy for a library)

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

```bash
curl --request GET \
  --url https://api.digitalsamba.com/api/v1/libraries/ec463c74-b227-4bec-9c95-b3eb515b6548/hierarchy \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY
```

{% 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
String libraryId = "ec463c74-b227-4bec-9c95-b3eb515b6548";

HttpRequest request = HttpRequest.newBuilder()
  .GET()
  .uri(new URI("https://api.digitalsamba.com/api/v1/libraries/" + libraryId + "/hierarchy"))
  .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 %}

#### Response (200 OK)

```json
{
    "id": "ec463c74-b227-4bec-9c95-b3eb515b6548",
    "external_id": null,
    "name": "Holiday in Greece",
    "source": "api",
    "created_at": "2024-10-07T11:32:56Z",
    "files": [
        {
            "id": "5fa70307-e4eb-4819-b9f2-38985cbe9b9f",
            "name": "starship.png",
            "type": "image",
            "size": 839030,
            "source": "api",
            "status": "completed",
            "created_at": "2024-10-14T11:44:43Z"
        },
        ................
    ],
    "folders": [
        {
            "id": "e6a08bd6-7262-4fa2-8adf-1f7ddefe6907",
            "name": "Holiday",
            "source": "api",
            "created_at": "2024-10-14T10:16:24Z",
            "files": [
                {
                    "id": "5fa70307-e4eb-4819-b9f2-38985cbe9b9f",
                    "name": "itinerary.pdf",
                    "type": "pdf",
                    "size": 1839030,
                    "source": "api",
                    "status": "completed",
                    "created_at": "2024-10-15T15:02:16Z"
                }
            ],
            "folders": [
                {
                    "id": "079826ac-be5a-4af0-b555-40393241c376",
                    "name": "Greece",
                    "source": "api",
                    "created_at": "2024-10-14T10:20:10Z"
                },
                .............
            ]
        },
        ................
    ]
} 
```

The whole hierarchy of folders and files in each folder is being returned. Every **folder** object has a "**folders**" and "**files**" arrays. Of course these arrays can be empty if no folders or files are available in this folder.