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


---

# 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.datarhei.com/core/api/filesystem/s3.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.