> For the complete documentation index, see [llms.txt](https://docs.datarhei.com/core/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.datarhei.com/core/api/filesystem/s3.md).

# S3

S3 filesystems are only accessible via HTTP their configured mountpoint. Use the `POST` or `PUT` method with the path to that file to (over-)write a file. The body of the request contains the contents of the file. No particular encoding or `Content-Type` is required. The file can then be downloaded from the same path.

This filesystem is practical rarely changing data (e.g. VOD) for long term storage.

{% hint style="info" %}
On this page and in the examples we assume that a S3 storage with the name `aws` is mounted on `/awsfs`.
{% endhint %}

{% tabs %}
{% tab title="PUT/POST" %}

```shell
curl http://127.0.0.1:8080/awsfs/path/to/a/file.txt -X PUT -d @somefile.txt
```

{% endtab %}

{% tab title="GET" %}

```shell
curl http://127.0.0.1:8080/awsfs/path/to/a/file.txt -o file.txt
```

{% endtab %}

{% tab title="DELETE" %}

```shell
curl http://127.0.0.1:8080/awsfs/path/to/a/file.txt -X DELETE
```

{% endtab %}
{% endtabs %}

The returned `Content-Type` is based solely on the file extension. For a list of known mime-types and their extensions see [storage.mime\_types](/core/configuration/storage.md#mime-types) in the configuration.

## Access protection

It is strongly recommended to enable a username/password (HTTP Basic-Auth) protection for any `PUT/POST` and `DELETE` operations on /memfs. `GET` operations are not protected.

{% content-ref url="/pages/mTke84b6JtQeiOVoK9sj" %}
[S3](/core/configuration/storage/s3.md)
{% endcontent-ref %}

By default HTTP Basic-Auth is not enabled.

## API

The contents of the S3 filesystem mounted on `/awsfs` are also accessible via the API in the same way as described above, but with the same protection as the API (see [API-Security configuration](/core/configuration/api-security.md#auth)) for all operations. It is also possible to list all files that are currently in the filesystem.

### Create, Update

Example:

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

```bash
echo 'test' > example.txt && \
curl http://127.0.0.1:8080/api/v3/fs/aws/example.txt \
   -d @example.txt \
   -X PUT
```

{% endtab %}

{% tab title="PyClient" %}

```python
from core_client import Client

client = Client(base_url="http://127.0.0.1:8080")
client.login()

client.v3_fs_put_file(
    name: "aws",
    path: "example.txt",
    data: b"test"
)
```

{% endtab %}

{% tab title="GoClient" %}

```go
import (
    "strings"
    "github.com/datarhei/core-client-go/v16"
)

client, _ := coreclient.New(coreclient.Config{
    Address: "https://127.0.0.1:8080",
})

data := strings.NewReader("test")
err := client.FilesystemAddFile("aws", "/example.txt", data)
```

The contents for the upload has to be provided as an `io.Reader`.
{% endtab %}
{% endtabs %}

After the successful upload the file is available at `/awsfs/example.txt` and `/api/v3/fs/aws/example.txt`.

Description:

{% openapi src="/files/V11JtvWPW76agz6p3fTm" path="/api/v3/fs/{name}/{path}" method="put" %}
[doc-16.12.0.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2FtNYJCg6GDZV2tOUcjzOt%2Fdoc-16.12.0.json?alt=media\&token=ca0f4565-35e8-4e2c-97a6-10346f96231b)
{% endopenapi %}

### Read

#### List all files

Listing all currently stored files is done by calling `/api/v3/fs/aws`. It also accepts the query parameters `pattern`, `sort` (`name,` `size,` or `lastmod`) and `order` (`asc` or `desc`). If none of the parameters are given, all files will be listed sorted by their last modification time in ascending order.

With the `pattern` parameter you can filter the list based on a [glob pattern](https://en.wikipedia.org/wiki/Glob_\(programming\)), with the addition of the `**` placeholder to include multiple subdirectories, e.g. listing all `.ts` file in the root directory has the pattern `/*.ts`, listing all `.ts` file in the whole filesystem has the pattern `/**.ts`.

Example:

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

```bash
curl "http://127.0.0.1:8080/api/v3/fs/aws?sort=name&order=asc" \
   -X GET
```

{% endtab %}

{% tab title="PyClient" %}

```python
from core_client import Client

client = Client(base_url="http://127.0.0.1:8080")
client.login()

core_memfs_list = client.v3_fs_get_file_list(name="aws")
print(core_memfs_list)
```

{% endtab %}

{% tab title="GoClient" %}

```go
import (
    "fmt"
    "github.com/datarhei/core-client-go/v16"
)

client, _ := coreclient.New(coreclient.Config{
    Address: "https://127.0.0.1:8080",
})

files, err := client.FilesystemList("aws", "/*.", coreclient.SORT_NAME, coreclient.ORDER_ASC)

for _, file := range files {
    fmt.Printf("%+v\n", file)
}
```

{% endtab %}
{% endtabs %}

Description:

{% openapi src="/files/V11JtvWPW76agz6p3fTm" path="/api/v3/fs/{name}" method="get" %}
[doc-16.12.0.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2FtNYJCg6GDZV2tOUcjzOt%2Fdoc-16.12.0.json?alt=media\&token=ca0f4565-35e8-4e2c-97a6-10346f96231b)
{% endopenapi %}

#### Download a file

For downloading a file you have to specify the complete path and filename. The `Content-Type` will always be `application/data`.

Example:

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

```bash
curl http://127.0.0.1:8080/api/v3/fs/aws/example.txt \
   -X GET
```

{% endtab %}

{% tab title="PyClient" %}

```python
from core_client import Client

client = Client(base_url="http://127.0.0.1:8080")
client.login()

core_memfs_file = client.v3_fs_get_file(
    name="aws",
    path="example.txt"
)
print(core_memfs_file)
```

{% endtab %}

{% tab title="GoClient" %}

```go
import (
    "github.com/datarhei/core-client-go/v16"
)

client, _ := coreclient.New(coreclient.Config{
    Address: "https://127.0.0.1:8080",
})

data, err := client.FilesystemGetFile("aws", "/example.txt")
defer data.Close()
```

The returned data is an `io.ReadCloser`.
{% endtab %}
{% endtabs %}

Description:

{% openapi src="/files/V11JtvWPW76agz6p3fTm" path="/api/v3/fs/{name}/{path}" method="get" %}
[doc-16.12.0.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2FtNYJCg6GDZV2tOUcjzOt%2Fdoc-16.12.0.json?alt=media\&token=ca0f4565-35e8-4e2c-97a6-10346f96231b)
{% endopenapi %}

### Delete

For deleting a file you have to specify the complete path and filename.

Example:

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

```bash
curl http://127.0.0.1:8080/api/v3/fs/aws/example.txt \
   -X DELETE
```

{% endtab %}

{% tab title="PyClient" %}

```python
from core_client import Client

client = Client(base_url="http://127.0.0.1:8080")
client.login()

client.v3_fs_delete_file(
    name="aws",
    path="example.txt"
)
```

{% endtab %}

{% tab title="GoClient" %}

```go
import (
    "github.com/datarhei/core-client-go/v16"
)

client, _ := coreclient.New(coreclient.Config{
    Address: "https://127.0.0.1:8080",
})

err := client.FilesystemDeleteFile("aws", "/example.txt")
```

{% endtab %}
{% endtabs %}

Description:

{% openapi src="/files/V11JtvWPW76agz6p3fTm" path="/api/v3/fs/{name}/{path}" method="delete" %}
[doc-16.12.0.json](https://951110271-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQRvnKSkK1SsZB0HeYhh%2Fuploads%2FtNYJCg6GDZV2tOUcjzOt%2Fdoc-16.12.0.json?alt=media\&token=ca0f4565-35e8-4e2c-97a6-10346f96231b)
{% endopenapi %}

## Configuration

{% content-ref url="/pages/mTke84b6JtQeiOVoK9sj" %}
[S3](/core/configuration/storage/s3.md)
{% endcontent-ref %}