English

Swan API

This is a Postman Collection for the Swan 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

NameTypeDescription

email

string

password

string

{
  "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

NameTypeDescription

key_name

string

{
  "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

NameTypeDescription

access_token

string

apikey

string

{
  "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

NameTypeDescription

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

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.

{
  "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

NameTypeDescription

authorization

string

Request Body

NameTypeDescription

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

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

NameTypeDescription

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

{
  "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

NameTypeDescription

limit

integer

The number of items to return in the response

offset

integer

Page number, starts from 0. Default: 0

Headers

NameTypeDescription

authorization

string

Bearer token

{
  "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

NameTypeDescription

limit

integer

Number of items in one page. Default: 10

offset

integer

Page number, starts from 0. Default: 0

{
  "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 Swan Platform.

Headers

NameTypeDescription

authorization

string

Bearer token

Request Body

NameTypeDescription

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

{
  "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

NameTypeDescription

limit

integer

The number of items to return in the response. Default: 20

offser

integer

Page number, starts from 0. Default: 0

Deals.

Get storage provider

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

NameTypeDescription

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

NameTypeDescription

authorization

string

Bearer token

{
    "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

NameTypeDescription

authorization

string

Bearer token

Request Body

NameTypeDescription

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.

{
  "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

NameTypeDescription

authorization

string

Bearer token

Request Body

NameTypeDescription

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

{
  "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 Swan 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.

PreviousAcquire Testnet USDC and MATIC tokensNextMCS API

Last updated