> For the complete documentation index, see [llms.txt](https://docs-cn.filswan.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-cn.filswan.com/kai-fa-zi-yuan/fs3-api.md).

# FS3 API

## Authentication

Login FilSwan Platform to get the authorization token which is used to acquire an access key pair for login FS3.

## Acquire Access Key Pair

<mark style="color:blue;">`GET`</mark> `https://<access_url>/minio`

This endpoint allows you to acquire an access key pair.

#### Headers

| Name         | Type   | Description                                        |
| ------------ | ------ | -------------------------------------------------- |
| Bearer Token | string | This token can be issued via Platform 'login' API. |

{% tabs %}
{% tab title="200 The access key pair is successfully acquired." %}

```
{
    "data": {
        "access_key": "<access_key>",
        "access_url": "<access_url>",
        "secret_key": "<secret_key>"
    },
    "status": "success"
}
```

{% endtab %}

{% tab title="401 A valid authorization token is necessary to acquire the access key pair." %}

```
{
    "message": "Please provide a valid auth token.",
    "status": "fail"
}
```

{% endtab %}
{% endtabs %}

## Login FS3

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to acquire a token which is designed to do authorization before performing any actions for safety consideration.

#### Headers

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| User-Agent | string |             |

#### Request Body

| Name    | Type   | Description                                                                     |
| ------- | ------ | ------------------------------------------------------------------------------- |
| id      | string | 1                                                                               |
| jsonrpc | string | 2.0                                                                             |
| method  | string | web.Login                                                                       |
| params  | array  | Input 'username' which is 'access\_key', and 'password' which is 'secret\_key'. |

{% tabs %}
{% tab title="200 Successfully login." %}

```
{"jsonrpc":"2.0","result":{"token":"<bearer_token>","uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Bucket Management

## Get Bucket List

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to get a list of all buckets.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| User-Agent    | string |                                                 |
| Authorization | string | The bearer token is issued via 'login FS3' API. |

#### Request Body

| Name    | Type   | Description     |
| ------- | ------ | --------------- |
| id      | string | 1               |
| jsonrpc | string | 2.0             |
| method  | string | web.ListBuckets |
| params  | array  |                 |

{% tabs %}
{% tab title="200 Successfully got bucket list." %}

```
{"jsonrpc":"2.0","result":{"buckets":[{"name":"<example1>","creationDate":"2021-06-07T01:19:38.758964923Z"},{"name":"<example2>","creationDate":"2021-07-08T23:55:02.836502071Z"}],"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Create Bucket

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to create a bucket.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description        |
| ------- | ------ | ------------------ |
| id      | string | 1                  |
| jsonrpc | string | 2.0                |
| method  | string | web.MakeBucket     |
| params  | array  | input 'bucketName' |

{% tabs %}
{% tab title="200 Successfully created the bucket." %}

```
{"jsonrpc":"2.0","result":{"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Delete Bucket

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to delete the bucket you selected.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description        |
| ------- | ------ | ------------------ |
| id      | string | 1                  |
| jsonrpc | string | 2.0                |
| method  | string | web.DeleteBucket   |
| params  | array  | Input 'bucketName' |

{% tabs %}
{% tab title="200 Successfully deleted the bucket." %}

```
{"jsonrpc":"2.0","result":{"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Get Bucket Policy List

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to get a list of policies of the bucket you selected.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description               |
| ------- | ------ | ------------------------- |
| id      | string | 1                         |
| jsonrpc | string | 2.0                       |
| method  | string | web.ListAllBucketPolicies |
| params  | array  | Input 'bucketName'        |

{% tabs %}
{% tab title="200 Successfully got the policy list." %}

```
{"jsonrpc":"2.0","result":{"uiVersion":"2019-09-11T18:31:07Z","policies":[{"bucket":"<bucket_name>","prefix":"<policy_name>","policy":"<policy_type>"}]},"id":1}
```

{% endtab %}
{% endtabs %}

## Edit Bucket Policy

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to add or remove a policy of the bucket you selected.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' Api. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description                            |
| ------- | ------ | -------------------------------------- |
| id      | string | 1                                      |
| jsonrpc | string | 2.0                                    |
| method  | string | web.SetBucketPolicy                    |
| params  | array  | Input 'bucketName', 'policy', 'prefix' |

{% tabs %}
{% tab title="200 Successfully edited bucket policy." %}

```
{"jsonrpc":"2.0","result":{"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Backup Bucket to Filecoin - online deal

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/deals/<bucket>`

This endpoint allows you to backup the bucket you selected to Filecoin network as an online deal.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| MinerId       | string | provider ID |
| Price         | string | unit: fil   |
| Duration      | string | unit: epoch |
| VerifiedDeal  | string | true/false  |
| FastRetrieval | string | true/false  |

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

```
{
    "data": {
        "filename": "~/minio-data/test_deals.zip",
        "walletAddress": "h376xbytsd3jie6ermpw",
        "verifiedDeal": "false",
        "fastRetrieval": "true",
        "dataCid": "bafk2bza5dgw6pubjodkscqpg",
        "minerId": "t03354",
        "price": "0.000005",
        "duration": "518800",
        "dealCid": "bafyreicvqh7krdhdnpkqwokze",
        "timeStamp": "1629835134146540"
    },
    "status": "success",
    "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Backup Bucket to Filecoin - offline deal

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/offlinedeals/<bucket>`

This endpoint allows you to backup the bucket you selected to Filecoin network as an offline deal.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name             | Type   | Description                                                                                              |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------- |
| Task\_Name       | string | Task name you preferred.                                                                                 |
| Curated\_Dataset | string |                                                                                                          |
| Description      | string |                                                                                                          |
| Is\_Public       | string | The task is whether public or private. The possible values: 1, 0                                         |
| Type             | string | The deals in this task is whether regular or verified. the possible values: regular, verified.           |
| Miner\_Id        | string | The provider you want to assign the task to. Required if is\_public is set to 0.                         |
| Min\_Price       | string | Min price per Gib per epoch.                                                                             |
| Max\_Price       | string | Max price per Gib per epoch.                                                                             |
| Tags             | string | Up to 5 tags.                                                                                            |
| Expire\_Days     | string |                                                                                                          |
| Auto\_bid        | string | The task is available to auto-bid or not. The possible values: 1, 0. Required if is\_public is set to 1. |

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

```
{
    "data": {
        "bucket_name": "test",
        "deals": {
            "data": {
                "taskname": "test-name",
                "filename": "be450523-52ed-44f9-9828-8e382c0d15c8.csv",
                "uuid": "d2d79d42-6f79-46fe-97bd-cd6f69c25116"
            },
            "status": "success",
            "message": "Task created successfully.A notification email has been sent to the storage provider"
        }
    },
    "status": "success",
    "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Retrieve Bucket from Filecoin - online deal

<mark style="color:blue;">`GET`</mark> `https://<access_url>/minio/bucket/retrieve/<bucket>`

This endpoint allows you to retrieve the bucket you selected from Filecoin network.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

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

```
{
    "data": {
        "bucket_name": "20210824",
        "deals": [
            {
                "data": {
                    "filename": "~/minio-data/test_deals.zip",
                    "walletAddress": "t3u7pum2vzyasg7cimkpnojqd3jie6erm",
                    "verifiedDeal": "false",
                    "fastRetrieval": "true",
                    "dataCid": "bafykbvgxdpej7neeoqsnvuzppme",
                    "minerId": "t03354",
                    "price": "0.000005",
                    "duration": "518700",
                    "dealCid": "bafyrekm3lmusljgmvyriqid6kcaoed5kni",
                    "timeStamp": "1629816006709676"
                },
                "status": "success",
                "message": "success"
            },
            {
                "data": {
                    "filename": "~/minio-data/test_deals.zip",
                    "walletAddress": "t3u7khtadjzfydxxdanojqd3jie6ermpw",
                    "verifiedDeal": "false",
                    "fastRetrieval": "true",
                    "dataCid": "bafykbnvz5rgs7obwbfztqrr4ahwjue",
                    "minerId": "t03354",
                    "price": "0.000005",
                    "duration": "518800",
                    "dealCid": "bafyrgigdm4ppqzwt4vufm4m3pmuvolnfe",
                    "timeStamp": "1629833844752891"
                },
                "status": "success",
                "message": "success"
            }
        ]
    },
    "status": "success",
    "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Object Management

## Get Objects List

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to get a list of all objects of the bucket you selected.&#x20;

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description                  |
| ------- | ------ | ---------------------------- |
| id      | string | 1                            |
| jsonrpc | string | 2.0                          |
| method  | string | web.ListObjects              |
| params  | array  | Input 'bucketName', 'prefix' |

{% tabs %}
{% tab title="200 Successfully get objects List" %}

```
{"jsonrpc":"2.0","result":{"objects":[{"name":"example_file","lastModified":"2021-06-07T01:19:38.758964923Z","size":0,"contentType":"application/octet-stream"}],"writable":true,"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Upload Object

<mark style="color:orange;">`PUT`</mark> `https://<access_url>/minio/upload/<bucket>/<object>`

This endpoint allows you to upload objects to the bucket you selected.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |
| x-amz-date    | string |                                                 |

#### Request Body

| Name   | Type   | Description                            |
| ------ | ------ | -------------------------------------- |
| object | object | Select the file you desired to upload. |

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

```
```

{% endtab %}
{% endtabs %}

## Get URL Token

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to get a URL token for downloading objects.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description        |
| ------- | ------ | ------------------ |
| id      | string | 1                  |
| jsonrpc | string | 2.0                |
| method  | string | web.CreateURLToken |
| params  | string |                    |

{% tabs %}
{% tab title="200 Successfully downloaded the object." %}

```
{"jsonrpc":"2.0","result":{"token":"<bearer_token>","uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Download Objects

<mark style="color:blue;">`GET`</mark> `https://<access_url>/minio/download/<bucket>/<object>`

This endpoint allows you to download objects.

#### Path Parameters

| Name  | Type   | Description                                   |
| ----- | ------ | --------------------------------------------- |
| token | string | This token is issued via 'get URL Token' API. |

#### Headers

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
| User-Agent | string |             |

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

```
```

{% endtab %}
{% endtabs %}

## Delete Object

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to delete the object you selected.

#### Headers

| Name          | Type   | Description                                    |
| ------------- | ------ | ---------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API |
| User-Agent    | string |                                                |
| x-amz-date    | string |                                                |

#### Request Body

| Name    | Type   | Description                   |
| ------- | ------ | ----------------------------- |
| id      | string | 1                             |
| jsonrpc | string | 2.0                           |
| method  | string | web.RemoveObject              |
| params  | array  | Input 'bucketName', 'objects' |

{% tabs %}
{% tab title="200 Successfully deleted the object." %}

```
{"jsonrpc":"2.0","result":{"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Share Object

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to share the object you selected.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| User-Agent    | string |                                                 |
| Authorization | string | The bearer token is issued via 'login FS3' API. |

#### Request Body

| Name    | Type   | Description                                 |
| ------- | ------ | ------------------------------------------- |
| id      | string | 1                                           |
| jsonrpc | string | 2.0                                         |
| method  | string | web.PresignedGet                            |
| params  | array  | Input 'bucket', 'expiry', 'host', 'object'. |

{% tabs %}
{% tab title="200 Successfully get the sharable link." %}

```
{"jsonrpc":"2.0","result":{"uiVersion":"2019-09-11T18:31:07Z","url":"<object_directory>?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=UBFSNUG8AZIII4XOMUTW%2F20210903%2F%2Fs3%2Faws4_request\u0026X-Amz-Date=20210903T182225Z\u0026X-Amz-Expires=<expiry_time>\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=d35eb873a0c3bb0ea316c550b6259ce5f5eb7ba08da8a5c813721eae1f654b78"},"id":1}
```

{% endtab %}
{% endtabs %}

## Backup Object to Filecoin - online deal

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/deal/<bucket>/<object>`

This endpoint allows you to backup the object you selected to Filecoin network.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| User-Agent    | string |                                                 |
| Authorization | string | The bearer token is issued via 'login FS3' API. |

#### Request Body

| Name         | Type   | Description   |
| ------------ | ------ | ------------- |
| MinerId      | string | provider ID   |
| Price        | string | unit: fil     |
| Duration     | string | unict: epochs |
| VerifiedDeal | string | true/false    |
| FastRetrival | string | true/false    |

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

```
{
    "data": {
        "filename": "~/minio-data/test/waymo.zip",
        "walletAddress": "wabkhtadjzfydxxda2vzyasg7cimd3jie6ermpw",
        "verifiedDeal": "false",
        "fastRetrieval": "true",
        "dataCid": "bafykbzaceb5cfdrbg45khvhk4mza6",
        "minerId": "t03354",
        "price": "0.000005",
        "duration": "1036700",                    //epochs
        "dealCid": "bafyreicmqtttadqdksrqvunxhcgvfvb47m",
        "timeStamp": "1628025191856290"           //miliseconds
    },
    "status": "success",
    "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Retrieve Object from Filecoin - online deal

<mark style="color:blue;">`GET`</mark> `https://<access_url>/minio/retrieve/<bucket>/<object>`

This endpoint allows you to retrieve the object you selected from Filecoin network.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| User-Agent    | string |                                                 |
| Authorization | string | The bearer token is issued via 'login FS3' API. |

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

```
{
    "data": {
        "file_name": "waymo.zip",
        "deals": [
            {
                "data": {
                    "filename": "~/minio-data/test/waymo.zip",
                    "walletAddress": "5wabkhtadjzfydxxdq66j4dubbhwpnojqd3jmpw",
                    "verifiedDeal": "false",
                    "fastRetrieval": "true",
                    "dataCid": "bafykbzaceb5cfdpdupjd4mza6",
                    "minerId": "t03354",
                    "price": "0.000005",
                    "duration": "1036700",
                    "dealCid": "bafyreicmm2g654",
                    "timeStamp": "1628025191856290"
                },
                "status": "success",
                "message": "success"
            },
            {
                "data": {
                    "filename": "~/minio-data/testre/waymo.zip",
                    "walletAddress": "5wabkhtadjzfydxxda2vzyasg7cimkcphswrq66j4dubbhwpnoj",
                    "verifiedDeal": "false",
                    "fastRetrieval": "true",
                    "dataCid": "bafykbzaceb5cfdpdupjd4mza6",
                    "minerId": "t03354",
                    "price": "0.000005",
                    "duration": "1036700",
                    "dealCid": "bafyreijg227wlo4bge76bcxk7cw",
                    "timeStamp": "1628026238100552"
                },
                "status": "success",
                "message": "success"
            }
        ]
    },
    "status": "success",
    "message": "success"
}
```

{% endtab %}
{% endtabs %}

## General Settings

## Change Password

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to change password.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description                                                                   |
| ------- | ------ | ----------------------------------------------------------------------------- |
| id      | string | 1                                                                             |
| jsonrpc | string | 2.0                                                                           |
| method  | string | web.SetAuth                                                                   |
| params  | array  | Input 'currentAccessKey', 'currentSecretKey', 'newAccessKey', 'newSecretKey'. |

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

```
```

{% endtab %}
{% endtabs %}

## Get Storage Info

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

This endpoint allows you to get storage information.

#### Headers

| Name          | Type   | Description                                     |
| ------------- | ------ | ----------------------------------------------- |
| Authorization | string | The bearer token is issued via 'login FS3' API. |
| User-Agent    | string |                                                 |

#### Request Body

| Name    | Type   | Description     |
| ------- | ------ | --------------- |
| id      | string | 1               |
| jsonrpc | string | 2.0             |
| method  | string | web.StorageInfo |
| params  | string |                 |

{% tabs %}
{% tab title="200 Successfully got storage info." %}

```
{"jsonrpc":"2.0","result":{"storageInfo":{"Used":653465,"Total":7537270108160,"Available":4140889018368,"Backend":{"Type":1,"OnlineDisks":0,"OfflineDisks":0,"StandardSCData":0,"StandardSCParity":0,"RRSCData":0,"RRSCParity":0,"Sets":null}},"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}

## Get Server Info

<mark style="color:green;">`POST`</mark> `https://<access_url>/minio/webrpc`

#### Headers

| Name          | Type   | Description |
| ------------- | ------ | ----------- |
| Authorization | string |             |
| User-Agent    | string |             |

#### Request Body

| Name    | Type   | Description    |
| ------- | ------ | -------------- |
| id      | string | 1              |
| jsonrpc | string | 2.0            |
| method  | string | web.ServerInfo |
| params  | string |                |

{% tabs %}
{% tab title="200 Successfully got server info." %}

```
{"jsonrpc":"2.0","result":{"MinioVersion":"2019-09-11T18:33:15Z","MinioMemory":"Used: 6.8 MB | Allocated: 3.7 GB | Used-Heap: 6.8 MB | Allocated-Heap: 65 MB","MinioPlatform":"Host: 2f245ecded89 | OS: linux | Arch: amd64","MinioRuntime":"Version: go1.13 | CPUs: 24","MinioGlobalInfo":{"isBrowserEnabled":true,"isDistXL":false,"isEnvBrowser":false,"isEnvCreds":false,"isEnvRegion":false,"isSSL":false,"isWorm":false,"isXL":false,"serverRegion":""},"MinioUserInfo":{"isIAMUser":false},"uiVersion":"2019-09-11T18:31:07Z"},"id":1}
```

{% endtab %}
{% endtabs %}