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


---

# 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-cn.filswan.com/kai-fa-zi-yuan/fs3-api.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.