FilSwan API

This is a Postman Collection for the FilSwan API v2 endpoints. The page below describes different components of our API offering.

Authorization

These endpoints return details about Authorization.

Get Auth Token

POST https://api.filswan.com/auth/login

This endpoint allows you to get an JWT Bearer Token (auth_token) from email and password. The auth_token can be used for generate other API Keys.

Request Body

Name	Type	Description
email	string
password	string

200

{
  "auth_token": "eyJ0eXAiOiJKV1QiLCJhbGci1iJIUzI1NiJ9.eyJleHAi5jE2XTM4NDY2ODUsImlhdCI6MTYxMzc2MDI4NSwic3ViIjoxODB9.nqVR7pZ5voIEotp85zA2dEzIEmAMbiWcCBkvT06ILu4",
  "message": "Successfully logged in.",
  "status": "success"
}

Generate API Key

POST https://api.filswan.com/user/api_keys/jwt

This endpoint allows you to issue new API keys for their account programmatically. The only key-type that can be used to issue new keys is the login user's JWT Bearer Token. The purpose of this endpoint is to allow for programmatic creation of API keys that may be used for multiple projects, individual users, or a variety of other use cases where a single API key pair across an account is not sufficient. This endpoint will return three values: The API Key, the API Secrect, and a JWT Bearer Token. Make sure to record the API Secret and the JWT as they will not be accessible again.

Request Body

Name	Type	Description
key_name	string

200

{
  "auth_token": {
    "access_token": "6ca9a6575b7255b3f15xxxxxxxxxxx17a1",
    "apikey": "7WIhxxxxxxxxxx0YSmGw",
    "created_on": "1614229867",
    "jwt": "eyJ0eXAiOiJxxxxxxxxxxxOiJIUzI1NiJ9.eyJleHAiOjExxxxxxxxxxxxDIyOTg2Nywic3ViIjoiN1dJaGM5bkNrR1gzVk9VczBZU21HdyJ9.CO5oXVnDGcTwxxxxxxxI6xC5IBF2NdJkt34",
    "key_name": "test",
    "status": "Created"
  },
  "message": "api token successfully created.",
  "status": "success"
}

Generate JWT token

POST https://api.filswan.com/user/api_keys/jwt

To use the bearer authentication model, you will need the JWT that is generated using this API. This token can be used as an Authorization header for all your API requests in the following format: "Authorization": "Bearer YOUR_JWT"

Request Body

Name	Type	Description
access_token	string
apikey	string

200

{
  "data": {
    "api_key": "my-apikey-name",
    "jwt": "my-api-token"
  },
  "status": "success"
}

Miners

These endpoints return details about storage providers specified by the requested IDs.

List Storager Provider

GET https://api.filswan.com/miners?limit={{limit}}&offset={{offset}}&location={{location}}&offline_deal_available={{offline_deal_available}}&status={{status}}&sort_by={{sort_by}}&order={{order}}

This endpoint allows you to get a list of storage providers.

Path Parameters

Name	Type	Description
limit	integer	Number of items in one page. Default: 10
offset	integer	Page number, starts from 0. Default: 0
location	string	The location of miners. If empty, it shows miners at all locations. Possible values: Global, Asia, Africa, North America, South America, Europe, Oceania
offline_deal_available	integer	Miner accept offline deals or not. If empty, it shows all miners. Possible values: 1, 0
status	string	The status of miners. If empty, it shows all miners in any status. Possible values: Active, Offline.
sort_by	string	Possible values: update_time_str, price, verified_price, score, status, location
order	string	Possible values: asc, desc

200

Single Storage Providers Detail

GET https://api.filswan.com/miners/{{miner_id}}

This endpoint allows you to get details of the miner specified by the requested provider ID.

200

{
  "data": {
    "miner": {
      "contact_info": "Charles Cao-NBFS",
      "location": "North America",
      "max_piece_size": "32 GiB",
      "min_piece_size": "8 MiB",
      "miner_id": "f019104",
      "offline_deal_available": true,
      "price": "1.8000000000E-8",
      "score": 0,
      "status": "Active",
      "update_time_str": "1609973690",
      "verified_price": "0E-18"
    }
  },
  "status": "success"
}

Update Storage Provider Info

POST https://api.filswan.com/miner/info

This endpoint allows you to update your storage provider information.

Headers

Name	Type	Description
authorization	string

Request Body

Name	Type	Description
miner_fid	string
bid_mode	integer	Possible values: 1,0
start_epoch	number
location	string
offline_deal_available	string	Possible values: true/false
expected_sealing_time	number

200

Tasks

These endpoints return details about tasks specified by the requested IDs.

Public Tasks

List Public Tasks

GET https://api.filswan.com/tasks?created_after={{created_after}}&has_miner={{has_miner}}&status={{status}}&is_public={{is_public}}&task_name={{task_name}}&type={{type}}&tags={{tags}}&max_price={{max_price}}&min_price={{min_price}}

This endpoint allows you to get a list of public tasks.

Path Parameters

Name	Type	Description
created_after	integer	Filter tasks after a specific time. If empty, it shows all tasks created at any time. Value is Unix timestamp in seconds.
has_miner	integer	Filter tasks had already been designated to a miner or not. If empty, show all tasks. Possible values: 1, 0
status	string	Filter tasks in various status. If empty, it shows tasks in any status. Possible values: created, completed.
is_public	integer	Tasks are public or private. Possible values: 1, 0
task_name	string	Search tasks by task name
type	string	The deals in this task is verified or not. Possible values: regular, verified
tags	string	Search tasks by tags. Use comma to separate multiple tags.
max_price	number	Max price per Gib per epoch
min_price	number	Min price per Gib per epoch

200

{
  "data": {
    "task": [
      {
        "bid_count": 0,
        "created_on": "1614106962",
        "deal_count": 22,
        "description": "Enter up to 5 tags that best describe your task. Miner will use these tags to find task they are most interested and experienced in.\n",
        "expire_days": null,
        "is_public": 1,
        "max_price": null,
        "min_price": null,
        "miner_id": null,
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "import_deal_template (3).csv",
        "task_id": 145,
        "task_name": "COMMON-CRAWL",
        "type": "regular"
      },
      {
        "bid_count": 1,
        "created_on": "1613713470",
        "deal_count": 1,
        "description": "NBFS fix auto import for API TOKEN, 8gb file, 160gb after seal",
        "expire_days": 4,
        "is_public": 1,
        "max_price": "0E-18",
        "min_price": "0E-18",
        "miner_id": null,
        "status": "Created",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "20210203_csv-verified-public.csv",
        "task_id": 125,
        "task_name": "NBFS fix auto import",
        "type": "verified"
      },
      {
        "bid_count": 2,
        "created_on": "1613682476",
        "deal_count": 1,
        "description": "Total of 320Gb verified deals will be 3,2Tb of power\nNeeds to be in the EU",
        "expire_days": 3,
        "is_public": 1,
        "max_price": null,
        "min_price": null,
        "miner_id": null,
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "deal-empty-for-now.csv",
        "task_id": 124,
        "task_name": "10x 32Gb verified sectors - 2",
        "type": "verified"
      },
      {
        "bid_count": 0,
        "created_on": "1613682370",
        "deal_count": 1,
        "description": "Total of 320Gb verified deals will be 3,2Tb of power\nNeeds to be in the EU",
        "expire_days": 3,
        "is_public": 1,
        "max_price": null,
        "min_price": null,
        "miner_id": null,
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "deal-empty-for-now.csv",
        "task_id": 123,
        "task_name": "10x 32Gb verified sectors",
        "type": "verified"
      },
      {
        "bid_count": 2,
        "created_on": "1613418605",
        "deal_count": 4,
        "description": "Designed for test miner client function, big winner will get 160gb after testing.",
        "expire_days": 2,
        "is_public": 1,
        "max_price": "1.00000000000E-7",
        "min_price": "0E-18",
        "miner_id": "f047419",
        "status": "Created",
        "successful_deal_count": 1,
        "tags": "NBFS",
        "task_file_name": "f047419-0219.csv",
        "task_id": 121,
        "task_name": "NBFS 9GB Miner client test",
        "type": "verified"
      },
      {
        "bid_count": 3,
        "created_on": "1613174281",
        "deal_count": 2,
        "description": "This deal is for testing email notifications. you will get 160gb after sealing",
        "expire_days": 4,
        "is_public": 1,
        "max_price": "1.0000000E-11",
        "min_price": "0E-18",
        "miner_id": "f03624",
        "status": "Created",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "f03624_20210215.csv",
        "task_id": 120,
        "task_name": "NBFS 9GB",
        "type": null
      },
      {
        "bid_count": 2,
        "created_on": "1613161109",
        "deal_count": 2,
        "description": "10x verified deal.will be 160gb after seal",
        "expire_days": 4,
        "is_public": 1,
        "max_price": "1.0000000E-11",
        "min_price": "0E-18",
        "miner_id": "f047419",
        "status": "Completed",
        "successful_deal_count": 1,
        "tags": null,
        "task_file_name": "f047419_20210212.csv",
        "task_id": 119,
        "task_name": "NBFS 9GB",
        "type": null
      },
      {
        "bid_count": 6,
        "created_on": "1612567274",
        "deal_count": 1,
        "description": "Verified deal file with 10x sealing capability ,it will be 320GB after proving\n",
        "expire_days": 3,
        "is_public": 1,
        "max_price": null,
        "min_price": null,
        "miner_id": null,
        "status": "Created",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "film1.csv",
        "task_id": 116,
        "task_name": "Speedium-1612567082",
        "type": "verified"
      },
      {
        "bid_count": 5,
        "created_on": "1612448401",
        "deal_count": 2,
        "description": "9Gb file with 10x sealing capability ,it will be 160GB after proving",
        "expire_days": 4,
        "is_public": 1,
        "max_price": "1.50000000000E-7",
        "min_price": "1.00000000000E-7",
        "miner_id": "f023467",
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": "NA,EU",
        "task_file_name": "f023467_20210212.csv",
        "task_id": 115,
        "task_name": "Filbox Feb04-2 Task",
        "type": "verified"
      },
      {
        "bid_count": 6,
        "created_on": "1612443851",
        "deal_count": 2,
        "description": "Open to EU and NA miners",
        "expire_days": 4,
        "is_public": 1,
        "max_price": "1.5000000000E-8",
        "min_price": "1.0000000000E-8",
        "miner_id": "f010446",
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": "filbox",
        "task_file_name": "f010446_20200210.csv",
        "task_id": 114,
        "task_name": "Filbox Verified deal",
        "type": "verified"
      }
    ]
  },
  "status": "success",
  "total_items": 10,
  "total_task_count": 10
}

Client Tasks

List User Tasks

GET https://api.filswan.com/tasks?limit={{limit}}&offset={{offset}}

This endpoint allows you to get details of tasks created by a client.

Path Parameters

Name	Type	Description
limit	integer	The number of items to return in the response
offset	integer	Page number, starts from 0. Default: 0

Headers

Name	Type	Description
authorization	string	Bearer token

200

{
  "data": {
    "task": [
      {
        "bid_count": 0,
        "created_on": "1614106596",
        "deal_count": 22,
        "description": "Enter up to 5 tags that best describe your task. Miner will use these tags to find task they are most interested and experienced in.",
        "expire_days": null,
        "is_public": 0,
        "max_price": null,
        "min_price": null,
        "miner_id": "f001122",
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "import_deal_template (3).csv",
        "task_id": 143,
        "task_name": "COMMON-CRAWL",
        "type": "regular"
      },
      {
        "bid_count": 0,
        "created_on": "1614106085",
        "deal_count": 39,
        "description": "It has a General Storage Service (GS2) store unstructured data such as photos, videos, log files, backups and container images compatible with Amazon S3 cloud storage service.",
        "expire_days": null,
        "is_public": 0,
        "max_price": null,
        "min_price": null,
        "miner_id": "f001122",
        "status": "Completed",
        "successful_deal_count": 0,
        "tags": null,
        "task_file_name": "import_deal_template (3).csv",
        "task_id": 142,
        "task_name": "COMMON-CRAWL",
        "type": "regular"
      }
    ]
  },
  "status": "success",
  "total_items": 2,
  "total_task_count": 2
}

Single Task Details

GET https://api.filswan.com/tasks/{{task_uuid}}?limit={{limit}}&offset={{offset}}

This endpoint allows you to get details about the task specified by the requested task UUID.

Path Parameters

Name	Type	Description
limit	integer	Number of items in one page. Default: 10
offset	integer	Page number, starts from 0. Default: 0

200

{
  "data": {
    "average_bid": "0",
    "bid": [
      {
        "bid_id": 26,
        "contact_info": "slack: @Patrick - Factor8 Solutions",
        "created_on": "1613978960",
        "expire_days": 5,
        "min_piece_size": "16GB",
        "price": "0E-18",
        "proposal": "whatever you need man",
        "status": "New",
        "swan_user_info": {
          "headline": null,
          "miners": [
            {
              "location": "Global",
              "max_piece_size": "32 GiB",
              "min_piece_size": "256 B",
              "miner_id": "f03223",
              "offline_deal_available": false,
              "price": "5.000000000000000000",
              "score": 0,
              "status": "Deleted",
              "update_time_str": "1613951245947",
              "verified_price": "5.000000000000000000"
            },
            {
              "location": "Europe",
              "max_piece_size": "32 GiB",
              "min_piece_size": "16 GiB",
              "miner_id": "f062353",
              "offline_deal_available": true,
              "price": "5.0000000000E-8",
              "score": 0,
              "status": "Deleted",
              "update_time_str": "1613949072425",
              "verified_price": "0E-18"
            }
          ],
          "registered_on": "1613949072",
          "status": "Active",
          "summary": null
        },
        "task_id": 125,
        "username": "swancylmqovj",
        "won_on": null
      }
    ],
    "bid_count": 1,
    "deal": [
      {
        "created_at": "1613713470",
        "deal_cid": null,
        "file_path": null,
        "file_source_url": "https://download.nbai.io/CC-MAIN-20200918061627-20200918091627-00583-00584-00585-00586-00587-00588-00589.gz.car",
        "id": 2645,
        "md5_origin": null,
        "miner_id": null,
        "note": null,
        "start_epoch": null,
        "status": "Created",
        "task_id": 125,
        "updated_at": "1613713470",
        "user_id": 21
      }
    ],
    "deal_complete_rate": "0.00",
    "miner": null,
    "poster": {
      "complete_task_count": 39,
      "contact_info": "Charles Cao-NBFS",
      "member_since": "January 12, 2021"
    },
    "task": {
      "created_on": "1613713470",
      "description": "NBFS fix auto import for API TOKEN, 8gb file, 160gb after seal",
      "expire_days": 4,
      "is_public": 1,
      "max_price": "0E-18",
      "min_price": "0E-18",
      "miner_id": null,
      "status": "Created",
      "tags": null,
      "task_file_name": "20210203_csv-verified-public.csv",
      "task_id": 125,
      "task_name": "NBFS fix auto import",
      "type": "verified"
    },
    "total_deal_count": 1
  },
  "status": "success"
}

Create Task

POST https://api.filswan.com/tasks

This endpoint allows you to create a new task on FilSwan Platform.

Headers

Name	Type	Description
authorization	string	Bearer token

Request Body

Name	Type	Description
fast_retrieval	string	Possible values: true/false
bid_mode	string	This task is available for autobid or not. Possible values: 1, 0
task_name	string	Task name you prefered
is_public	integer	This task is whether public or private. The possible values: 1, 0
type	string	The deals in this task is whether regular or verified. Possible values: regular, verified
file	object	The CSV file containing all deal information in the task to create. It is required when creating a private task.
miner_id	string	The provider you want to assign the task to. Required if is_public is set to 0.
description	string
tags	string	Up to 5 tags. Use comma to separate multiple tags.
max_price	number	Max price per Gib per epoch
min_price	number	Min price per Gib per epoch

200

{
  "data": {
    "filename": "import_deal_template.csv"
  },
  "status": "success"
}

Storage Provider Tasks

List Storage Provider Tasks

GET https://api.filswan.com/my_miner/tasks?limit={{limit}}&offset={{offset}}

This endpoint allows you to get a list of tasks when your role is a miner.

Path Parameters

Name	Type	Description
limit	integer	The number of items to return in the response. Default: 20
offser	integer	Page number, starts from 0. Default: 0

200

Deals.

Get storage provider's deals by status

GET https://api.filswan.com/offline_deals/{{miner_fid}}?deal_status={{deal_status}}&limit={{limit}}&offset={{offset}}

This endpoint allows you to get a list of offline deals belongs to a specified provider ID.

Path Parameters

Name	Type	Description
deal_status	string	The deal status. Possible values: ReadyForImport, FileImporting, FileImported, DealActive, ImportFailed
limit	integer	The number of items to return in the response. Default: 20
offset	integer	Page number, starts from 0. Default: 0

Headers

Name	Type	Description
authorization	string	Bearer token

200

{
    "data": {
        "deal": [
            {
                "created_at": "1613398987",
                "deal_cid": "deal_cid",
                "file_path": "file_path",
                "file_source_url": "file_source_url",
                "id": 1,
                "md5_origin": null,
                "miner_id": 1,
                "note": "This is an example.",
                "start_epoch": 400300,
                "status": "ReadyForImport",
                "task_id": 1,
                "updated_at": "1613398987",
                "user_id": 1
            },
            {
                "created_at": "1613398987",
                "deal_cid": deal_cid",
                "file_path": "file_path",
                "file_source_url": "file_source_url",
                "id": 2,
                "md5_origin": null,
                "miner_id": 1,
                "note": "",
                "start_epoch": 400300,
                "status": "ReadyForImport",
                "task_id": 1,
                "updated_at": "1613398987",
                "user_id": 1
            }
        ]
    },
    "status": "success"
}

Update Single Deal Details

PUT https://api.filswan.com/my_miner/deals/<deal_cid>

Headers

Name	Type	Description
authorization	string	Bearer token

Request Body

Name	Type	Description
status	string	The new deal status. Possible values: FileImporting, FileImported, DealActive, ImportFailed
note	string	The additional information you would like to provide regarding the deal.
file_path	string	The path where the car file is downloaded.
file_size	string	The size of the car file.

200

{
  "data": {
    "deal": {
      "created_at": "1613398987",
      "deal_cid": "deal_cid",
      "file_path": "file_path",
      "file_source_url": "file_source_url",
      "id": 1,
      "md5_origin": null,
      "miner_id": 1,
      "note": "This is a test",
      "start_epoch": 400300,
      "status": "status",
      "task_id": 1,
      "updated_at": "1613398987",
      "user_id": 18
    },
    "message": "Deal updated successfully."
  },
  "status": "Success"
}

Update Deal Status

PUT https://api.filswan.com/my_miner/tasks/<task_uuid>/deals/<deal_cid>

Headers

Name	Type	Description
authorization	string	Bearer token

Request Body

Name	Type	Description
status	string	The new deal status. Possible values: FileImporting, FileImported, DealActive, ImportFailed
note	string	The additional information you would like to provide regarding the deal

200

{
  "data": {
    "deal": {
      "created_at": "1613398987",
      "deal_cid": "deal_cid",
      "file_path": "file_path",
      "file_source_url": "file_source_url",
      "md5_origin": "md5_origin",
      "miner_id": 1,
      "note": "note",
      "start_epoch": 400000,
      "status": "new-status",
      "task_id": 1,
      "updated_at": "1613398987"
    },
    "message": "Status new-status updated successfully."
  },
  "status": "success"
}

List of Supported API Methods

The list below documents the API methods that the FilSwan platform currently supports. When a response payload is present, all responses are returned in JSON format.

• Get Auth Token

• Generate API Key

• Generate JWT token

• List storage providers

• Single storage provider

• List Public Tasks

• List User Tasks

• Single task

• Create Task

• List storage provider Tasks

• Get storage provider's deals by status

• Update Single deal details

• Update deal status of a task

Find out more about our APIs.

If you have an API-related question, you can also discuss in the developer community forum.