Introduction

Latest version: v3

Welcome to the Skynet SDK docs!

We have SDK support for several languages:

Shell (using curl)
Browser JS
NodeJS
Python
Go

as well as the Skynet CLI (written in Go).

These SDKs are wrappers around HTTP calls to the corresponding Skynet endpoints. Full documentation for the Skynet HTTP API can be found in the Sia API Documentation.

A Note About Language Differences

Though we tried to keep the SDKs as similar to each other as possible in usage, differences between the languages -- the idiosyncracies and best practices of each -- resulted in differences between the SDKs. We've noted them where necessary throughout the documentation.

Case

In particular, note that the casing of functions and their parameters differs between the languages:

Language	Case
Javascript	`camelCase`
Python	`snake_case`
Go	`PascalCase`

For consistency throughout this document, functions and their parameters are documented using camelCase.

Standard Responses

Functions will respond with the desired content on success and with errors or exceptions on failure. The error messages may contain HTTP status codes (see the Sia Docs).

Functions will fail differently in each SDK depending on the language:

Language	Failure Mode
Javascript	Exceptions are raised and must be caught with a `try-catch` block.
Python	Same as above.
Go	Errors are returned and must be checked for explicitly.

Getting Started

Making Your First API Call

curl -X POST "https://siasky.net/skynet/skyfile" -F file=@image.jpg

skynet upload "./image.jpg"

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();

// Assume we have a file from an input form.

async function uploadExample() {
  try {
    const { skylink } = await client.upload(file);
  } catch (error) {
    console.log(error)
  }
}

const skynet = require('@nebulous/skynet');

(async () => {
    const skylink = await skynet.uploadFile("./image.jpg");
    console.log(`Upload successful, skylink: ${skylink}`);
})();

import siaskynet as skynet

skylink = skynet.upload_file("image.jpg")
print("Upload successful, skylink: " + skylink)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    skylink, err := skynet.UploadFile("./image.jpg", skynet.DefaultUploadOptions)
    if err != nil {
        panic("Unable to upload: " + err.Error())
    }
    fmt.Printf("Upload successful, skylink: %v\n", skylink)
}

The SDKs are set up to be as simple as possible. Despite the many options for configuration, most users will be able to get started with a single API call. In the example on the right, we upload the file image.jpg to the default Skynet portal, https://siasky.net.

Using A Different Portal

The default portal used is https://siasky.net for all SDKs except Browser JS, which tries to use the portal which is running the sky app. The default portal is accessible through the exported function, defaultPortalUrl, and no configuration is required to use it. Having a reasonable choice already selected keeps friction for new developers low. However, as Skynet is a decentralized project, it is also possible to use different portals.

In every SDK except Browser JS, a different portal can be passed in as part of the options for each function. See Setting Additional Options.

Browser JS

import SkynetClient from "skynet-js";

// Or SkynetClient() without arguments to use the default portal.
const client = new SkynetClient("https://some-other-portal.xyz");

async uploadExample() {
  try {
    const { skylink } = await client.upload(file);
  } catch (error) {
    console.log(error)
  }
}

In Browser JS you will need to first create a new client with the desired portal. The client can be initialized without arguments to use the default portal URL or the portal can be specified. See the code example on the right.

Setting Additional Options

Each SDK function also accepts additional options. These vary depending on the endpoint and are documented alongside each function.

Common Options

Every function accepts the following common options:

Option	Description	Default
`portalUrl`	The URL of the portal. (Not available in Browser JS)	`"https://siasky.net"`
`endpointPath`	The relative path on the portal where the endpoint may be found for the function being called. Some portals, for example, may offer alternate download paths.	`""`
`customUserAgent`	This option is available to change the User Agent, as some portals may reject user agents that are not `Sia-Agent` for security reasons.	`""`

Useful Constants

Here are some constants exported by the SDKs which may be of use in applications.

Constant	Description	Default
`defaultPortalUrl`	The default Skynet portal to use, if one is not provided.	`"https://siasky.net"`
`uriSkynetPrefix`	The Skynet URI prefix.	`"sia://"`

API Authentication

curl -X POST -A "Sia-Agent" --user "":"foobar" \
  "https://siasky.net/skynet/skyfile" -F file=@image.jpg

skynet upload "./image.jpg" --api-key "foobar" --custom-user-agent "Sia-Agent"

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();

async function authenticationExample() {
  try {
    const { skylink } = await client.upload(
      file,
      { APIKey: "foobar", customUserAgent: "Sia-Agent" }
    );
  } catch (error) {
    console.log(error);
  }
}

const skynet = require('@nebulous/skynet');

(async () => {
    const skylink = await skynet.uploadFile(
    "./image.jpg",
    { APIKey: "foobar", customUserAgent: "Sia-Agent" }
  );
    console.log(`Upload successful, skylink: ${skylink}`);
})();

import siaskynet as skynet

skylink = skynet.upload_file(
  "image.jpg",
  {"api_key": "foobar", "custom_user_agent": "Sia-Agent"}
)
print("Upload successful, skylink: " + skylink)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    opts := skynet.DefaultUploadOptions
    opts.APIKey = "foobar"
  opts.CustomUserAgent = "Sia-Agent"
    skylink, err := skynet.UploadFile("./image.jpg", opts)
    if err != nil {
        panic("Unable to upload: " + err.Error())
    }
    fmt.Printf("Upload successful, skylink: %v\n", skylink)
}

Portals will likely require authentication on several of their endpoints. This is to prevent unwanted modifications to the blocklist, portal list, etc.

If you are authorized to use password-protected endpoints on a portal, you may authenticate yourself by setting the APIKey custom option when calling a function.

Setting The User Agent

The portal may also require that certain sensitive requests contain a custom user agent header, usually Sia-Agent. This is for security purposes, as otherwise a malicious website could make requests to your local portal on your behalf and steal coins.

We want this to be an opt-in for now, so Sia-Agent is not currently the default. You may change the user agent header by setting the customUserAgent custom option.

More Information

For more information about authentication on portals and local siad instances please see the Sia Docs.

Uploading To Skynet

Uploading A File

curl -L -X POST "https://siasky.net/skynet/skyfile/<siapath>" -F file=@image.jpg

skynet upload "./image.jpg"

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();

// NOTE: This example is different from the other SDKs because we cannot just
// take a path to a local file.

async function uploadExample() {
  try {
    const { skylink } = await client.upload(file);
  } catch (error) {
    console.log(error)
  }
}

const skynet = require('@nebulous/skynet');

(async () => {
    const skylink = await skynet.uploadFile("./image.jpg");
    console.log(`Upload successful, skylink: ${skylink}`);
})();

import siaskynet as skynet

skylink = skynet.upload_file("image.jpg")
print("Upload successful, skylink: " + skylink)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    skylink, err := skynet.UploadFile("./image.jpg", skynet.DefaultUploadOptions)
    if err != nil {
        panic("Unable to upload: " + err.Error())
    }
    fmt.Printf("Upload successful, skylink: %v\n", skylink)
}

Uploading a file to Skynet can be done through a Skynet portal or your local siad instance.

Parameters

Field	Description
`path`	The local path where the file to upload may be found.

Browser JS:

Field	Description
`file`	The `File` object returned from an input form.

Additional Options

Field	Description	Default
`portalFileFieldName`	The field name for files on the portal. Usually should not need to be changed.	`"file"`
`portalDirectoryFileFieldName`	The field name for directories on the portal. Usually should not need to be changed.	`"files[]"`
`customFilename`	Custom filename. This is the filename that will be returned when downloading the file in a browser.	`""`
`customDirname`	Custom dirname. If this is empty, the base name of the directory being uploaded will be used by default.	`""`
`skykeyName`	The name of the skykey on the portal used to encrypt the upload.	`""`
`skykeyID`	The ID of the skykey on the portal used to encrypt the upload.	`""`
`timeout_seconds`	The timeout in seconds.	`""`

Response

{
  "skylink": "CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg",
  "merkleroot": "QAf9Q7dBSbMarLvyeE6HTQmwhr7RX9VMrP9xIMzpU3I",
  "bitfield": 2048
}

Successfully uploaded file! Skylink: sia://CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg

"CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

"sia://CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

"sia://CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

"sia://CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

Field	Description
`skylink`	This is the skylink that can be used when downloading to retrieve the file that has been uploaded. It is a 46-character base64 encoded string that consists of the merkle root, offset, fetch size, and Skylink version which can be used to access the content.
`merkleroot`	(`curl` only) This is the hash that is encoded into the skylink.
`bitfield`	(`curl` only) This is the bitfield that gets encoded into the skylink. The bitfield contains a version, an offset and a length in a heavily compressed and optimized format.

Uploading A Directory

curl -L -X POST "https://siasky.net/skynet/<siapath>?filename=images" -F files[]=@./images/image1.png -F files[]=@./images/image2.png

skynet upload "./images"

import { getRelativeFilePath, getRootDirectory, SkynetClient } from "skynet-js";

const client = new SkynetClient();

// Assume we have a list of files from an input form.

async function uploadDirectoryExample() {
  try {
    // Get the directory name from the list of files.
    // Can also be named manually, i.e. if you build the files yourself
    // instead of getting them from an input form.
    const filename = getRootDirectory(files[0]);

    // Use reduce to build the map of files indexed by filepaths
    // (relative from the directory).
    const directory = files.reduce((accumulator, file) => {
      const path = getRelativeFilePath(file);

      return { ...accumulator, [path]: file };
    }, {});

    const { skylink } = await client.uploadDirectory(directory, filename);
  } catch (error) {
    console.log(error);
  }
}

const skynet = require('@nebulous/skynet');

(async () => {
    const url = await skynet.uploadDirectory("./images");
    console.log(`Upload successful, url: ${url}`);
})();

import siaskynet as skynet

url = skynet.upload_directory("./images")
print("Upload successful, url: " + url)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    url, err := skynet.UploadDirectory("./images", skynet.DefaultUploadOptions)
    if err != nil {
        panic("Unable to upload: " + err.Error())
    }
    fmt.Printf("Upload successful, url: %v\n", url)
}

It is possible to upload a directory as a single piece of content. Doing this will allow you to address your content under one skylink, and access the files by their path. This is especially useful for webapps.

For example, let's say you upload a web app with the following simple structure:

src
|-- favicon.ico
|-- index.html
|-- css
    |-- main.css
|-- js
    |-- app.js

The four files can be accessed as follows:

[portal url]/[skylink]/favicon.ico
[portal url]/[skylink]/index.html
[portal url]/[skylink]/css/main.css
[portal url]/[skylink]/js/app.js

You can use relative links to refer to different files within a web app. For example, to link to the main.css resource from index.html you would do src="css/app.css.

Parameters

Field	Description
`path`	The local path where the directory to upload may be found.

Browser JS:

Field	Description
`directory`	Object containing `File`s from an input form to upload, indexed by their path strings.
`filename`	The name of the directory.

Additional Options

See Uploading A File.

Response

{
  "skylink": "EAAV-eT8wBIF1EPgT6WQkWWsb3mYyEO1xz9iFueK5zCtqg",
  "merkleroot": "QAf9Q7dBSbMarLvyeE6HTQmwhr7RX9VMrP9xIMzpU3I",
  "bitfield": 2048
}

Successfully uploaded directory! Skylink: sia://EAAV-eT8wBIF1EPgT6WQkWWsb3mYyEO1xz9iFueK5zCtqg

"EAAV-eT8wBIF1EPgT6WQkWWsb3mYyEO1xz9iFueK5zCtqg"

"sia://EAAV-eT8wBIF1EPgT6WQkWWsb3mYyEO1xz9iFueK5zCtqg"

"sia://EAAV-eT8wBIF1EPgT6WQkWWsb3mYyEO1xz9iFueK5zCtqg"

"sia://EAAV-eT8wBIF1EPgT6WQkWWsb3mYyEO1xz9iFueK5zCtqg"

See Uploading A File.

Uploading With Encryption

Coming Soon

skynet upload "./image.jpg" --skykey-name "my-skykey"

// NOTE: this feature has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();

// Assume we have a file from an input form.

async uploadEncryptionExample() {
  try {
    const { skylink } = await client.upload(file, { skykeyName: "my-skykey" });
  } catch (error) {
    console.log(error)
  }
}

// NOTE: this feature has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

(async () => {
    const skylink = await skynet.uploadFile(
        "./image.jpg",
        { skykeyName: "my-skykey" }
    );
    console.log(`Upload successful, skylink: ${skylink}');
})();

# NOTE: this feature has not yet been implemented for this SDK.

import siaskynet as skynet

skylink = skynet.upload_file("image.jpg", { skykeyName: "my-skykey" })
print("Upload successful, skylink: " + skylink)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    opts := skynet.DefaultUploadOptions
    opts.SkykeyName = "my-skykey"
    skylink, err := skynet.UploadFile("./image.jpg", opts)
    if err != nil {
        panic("Unable to upload: " + err.Error())
    }
    fmt.Printf("Upload successful, skylink: %v\n", skylink)
}

If you have a skykey on the portal you can ask the portal to encrypt the uploaded content for you. Simply pass the skykey name or ID in the custom options when uploading a file or directory.

See the additional options in Uploading A File.

Also see Encryption.

Downloading From Skynet

Downloading A File

curl -A "Sia-Agent" "https://siasky.net/CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

skynet download "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg" "./dst.jpg"

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

try {
  client.download(skylink);
  // Or client.open(skylink) to open it in a new browser tab.
} catch (error) {
  console.log(error);
}

const skynet = require('@nebulous/skynet');

const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

(async () => {
    await skynet.downloadFile("./dst.jpg", skylink);
    console.log('Download successful');
})();

import siaskynet as skynet

skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

skynet.download_file("./dst.jpg", skylink)
print("Download successful")

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
  const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

    err := skynet.DownloadFile("./dst.go", skylink, skynet.DefaultDownloadOptions)
    if err != nil {
        panic("Something went wrong, please try again.\nError: " + err.Error())
    }
    fmt.Println("Download successful")
}

This function downloads a skylink using http streaming. The call blocks until the data is received. There is a 30s default timeout applied to downloading a skylink. If the data can not be found within this 30s time constraint, a 404 error will be returned. This timeout is configurable.

Parameters

Field	Description
`path`	The local path where the file should be downloaded to.
`skylink`	The skylink that should be downloaded. The skylink can contain an optional path. This path can specify a directory or a particular file. If specified, only that file or directory will be returned. See Uploading A Directory for examples.

Browser JS:

Field	Description
`skylink`	The skylink that should be downloaded. The skylink can contain an

optional path. This path can specify a directory or a particular file. If specified, only that file or directory will be returned. See Uploading A Directory for examples.

Additional Options

Field	Description	Default
`skykeyName`	The name of the skykey on the portal used to decrypt the download.	`""`
`skykeyID`	The ID of the skykey on the portal used to decrypt the download.	`""`
`timeout_seconds`	The timeout in seconds.	`""`

Response

Empty on success.

Downloading A File From An Uploaded Directory

curl -A "Sia-Agent" "https://siasky.net/XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg/dir2/file3"

skynet download "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg/dir2/file2" "./dst.jpg"

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg/dir2/file3";

try {
  client.download(skylink);
} catch (error) {
  console.log(error);
}

const skynet = require('@nebulous/skynet');

const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg/dir2/file3";

(async () => {
    await skynet.downloadFile("./dst.jpg", skylink);
    console.log('Download successful');
})();

import siaskynet as skynet

skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg/dir2/file3"

skynet.download_file("./dst.jpg", skylink)
print("Download successful")

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
  const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg/dir2/file3"

    err := skynet.DownloadFile("./dst.go", skylink, skynet.DefaultDownloadOptions)
    if err != nil {
        panic("Something went wrong, please try again.\nError: " + err.Error())
    }
    fmt.Println("Download successful")
}

It is possible to download files from uploaded directories by appending their paths to the skylink. The examples here use the directory structure from Uploading A Directory to illustrate this.

Getting Metadata

curl -I -A "Sia-Agent" "https://siasky.net/CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

# NOTE: this function has not yet been implemented for this SDK.

skynet metadata "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

// NOTE: this function has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

async metadataExample() {
  try {
    const md = await client.metadata(skylink);
  } catch (error) {
    console.log(error);
  }
}

// NOTE: this function has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

(async () => {
    const md = await skynet.metadata(skylink);
    console.log(Get metadata successful');
})();

import siaskynet as skynet

skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

md = skynet.metadata(skylink)

// NOTE: this function has not yet been implemented for this SDK.

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

    md, err := skynet.Metadata(skylink, skynet.DefaultMetadataOptions)
    if err != nil {
        panic("Something went wrong, please try again.\nError: " + err.Error())
    }
    fmt.Printf("Get metadata successful, metadata: %+v\n", md)
}

It is possible to get metadata about a file or directory without fetching the entire content. These API calls will perform a HEAD request that fetches the headers for the given skylink. These headers are identical to the ones that would be returned if the request had been a GET request.

Parameters

Field	Description
`skylink`	The skylink that should be downloaded. The skylink can contain an optional path. This path can specify a directory or a particular file. If specified, only that file or directory will be returned.

Additional Options

See Downloading A File.

Response

{
  "mode":     640,
  "filename": "folder",
  "subfiles": {
    "folder/file1.txt": {
      "mode":         640,
      "filename":     "folder/file1.txt",
      "contenttype":  "text/plain",
      "offset":       0,
      "len":          6
    }
  }
}

{
  "mode":     640,
  "filename": "folder",
  "subfiles": {
    "folder/file1.txt": {
      "mode":         640,
      "filename":     "folder/file1.txt",
      "contenttype":  "text/plain",
      "offset":       0,
      "len":          6
    }
  }
}

{
  "mode":     640,
  "filename": "folder",
  "subfiles": {
    "folder/file1.txt": {
      "mode":         640,
      "filename":     "folder/file1.txt",
      "contenttype":  "text/plain",
      "offset":       0,
      "len":          6
    }
  }
}

{
  "mode":     640,
  "filename": "folder",
  "subfiles": {
    "folder/file1.txt": {
      "mode":         640,
      "filename":     "folder/file1.txt",
      "contenttype":  "text/plain",
      "offset":       0,
      "len":          6
    }
  }
}

{
  "mode":     640,
  "filename": "folder",
  "subfiles": {
    "folder/file1.txt": {
      "mode":         640,
      "filename":     "folder/file1.txt",
      "contenttype":  "text/plain",
      "offset":       0,
      "len":          6
    }
  }
}

{
  "mode":     640,
  "filename": "folder",
  "subfiles": {
    "folder/file1.txt": {
      "mode":         640,
      "filename":     "folder/file1.txt",
      "contenttype":  "text/plain",
      "offset":       0,
      "len":          6
    }
  }
}

Coming Soon

Downloading With Decryption

Coming Soon

skynet download [skylink] [destination] --skykey-name "my-skykey"

// NOTE: this feature has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

try {
  client.download(skylink, { skykeyName: "my-skykey" });
} catch (error) {
  console.log(error);
}

// NOTE: this feature has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

(async () => {
    await skynet.downloadFile(
        "./dst.jpg",
        skylink,
        { skykeyName: "my-skykey" }
    );
    console.log('Download successful');
})();

# NOTE: this feature has not yet been implemented for this SDK.

import siaskynet as skynet

skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

skynet.download_file("./dst.jpg", skylink, { skykeyName: "my-skykey" })
print("Download successful")

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

func main() {
    // Must have a 'skylink' from an earlier upload.

    opts := skynet.DefaultDownloadOptions
    opts.SkykeyName = "my-skykey"
    err := skynet.DownloadFile("./dst.go", skylink, opts)
    if err != nil {
        panic("Something went wrong, please try again.\nError: " + err.Error())
    }
    fmt.Println("Download successful")
}

If you have a skykey on the portal you can ask the portal to decrypt the downloaded content for you. Simply pass the skykey name or ID in the custom options when downloading.

See the additional options in Downloading A File.

Also see Encryption.

Encryption

Encryption and decryption in Skynet are performed using skykeys. Skykeys can be created and queried using the functions in this section. The name or ID of a skykey must be provided when uploading or downloading with encryption.

Creating A Skykey

curl -A "Sia-Agent"  -u "":<apipassword> --data "name=key_to_the_castle" "localhost:9980/skynet/createskykey"

skynet skykey create "testcreateskykey"

// NOTE: this function has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const name = "testcreateskykey";

async function createSkykeyExample() {
  try {
    const skykey = await client.createSkykey(name, "private-id");
  } catch (error) {
    console.log(error)
  }
}

// NOTE: this function has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

const name = "testcreateskykey";

(async () => {
    const skykey = await skynet.createSkykey(name, "private-id");
})();

# NOTE: this function has not yet been implemented for this SDK.

import siaskynet as skynet

name = "testcreateskykey"

skykey = skynet.create_skykey(name, "private-id")
print("Create skykey successful, skykey: " + skykey)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    const name = "testcreateskykey"

    fmt.Printf("Creating skykey with name %v...\n", name)
    skykey, err := skynet.CreateSkykey(name, "private-id", skynet.DefaultCreateSkykeyOptions)
    if err != nil {
        panic("Unable to create skykey: " + err.Error())
    }
    fmt.Printf("Created skykey %v\n", skykey)

This function creates a skykey stored under the given name.

Parameters

Parameter	Description
`name`	Desired name of the skykey.
`type`	Desired type of the skykey. The two supported types are `"public-id"` and `"private-id"`. Users should use `"private-id"` skykeys unless they have a specific reason to use `"public-id"` skykeys which reveal skykey IDs and show which skyfiles are encrypted with the same skykey.

Response

{
  "skykey": "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq?name=testskykey1",
  "name": "key_to_the_castle",
  "id": "ai5z8cf5NWbcvPBaBn0DFQ==",
  "type": "private-id"
}

Coming Soon

{
  "skykey": "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq?name=testskykey1",
  "name": "key_to_the_castle",
  "id": "ai5z8cf5NWbcvPBaBn0DFQ==",
  "type": "private-id"
}

{
  "skykey": "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq?name=testskykey1",
  "name": "key_to_the_castle",
  "id": "ai5z8cf5NWbcvPBaBn0DFQ==",
  "type": "private-id"
}

{
  "skykey": "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq?name=testskykey1",
  "name": "key_to_the_castle",
  "id": "ai5z8cf5NWbcvPBaBn0DFQ==",
  "type": "private-id"
}

{
  "skykey": "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq?name=testskykey1",
  "name": "key_to_the_castle",
  "id": "ai5z8cf5NWbcvPBaBn0DFQ==",
  "type": "private-id"
}

Field	Type	Description
`skykey`	string	Base-64 encoded Skykey
`name`	string	Name of the Skykey
`id`	string	ID of the Skykey
`type`	string	Desired type of the skykey. See above for more information.

Adding A Skykey

curl -A "Sia-Agent"  -u "":<apipassword> --data "skykey=BAAAAAAAAABrZXkxAAAAAAAAAAQgAAAAAAAAADiObVg49-0juJ8udAx4qMW-TEHgDxfjA0fjJSNBuJ4a" "localhost:9980/skynet/addskykey"

skynet skykey add "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq"

// NOTE: this function has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skykey = "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq";

async function addSkykeyExample() {
  try {
    await client.addSkykey(skykey);
  } catch (error) {
    console.log(error)
  }
}

// NOTE: this function has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

const skykey = "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq";

(async () => {
    await skynet.addSkykey(skykey);
})();

# NOTE: this function has not yet been implemented for this SDK.

import siaskynet as skynet

skykey = "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq"

skynet.add_skykey(skykey)
print("Add skykey successful")

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    const skykey = "skykey:AUI0eAOXWXHwW6KOLyI5O1OYduVvHxAA8qUR_fJ8Kluasb-ykPlHBEjDczrL21hmjhH0zAoQ3-Qq"

    fmt.Printf("Adding skykey %v...\n", skykey)
    err := skynet.AddSkykey(skykey, skynet.DefaultAddSkykeyOptions)
    if err != nil {
        panic("Unable to add skykey: " + err.Error())
    }

This function stores the given skykey with the renter's skykey manager.

Parameters

Parameter	Description
`skykey`	Base-64 encoded skykey

Response

Error or exception on failure.

Getting A Skykey By Name

curl -A "Sia-Agent"  -u "":<apipassword> --data "name=key_to_the_castle" "localhost:9980/skynet/skykey"

skynet skykey get name "testcreateskykey"

// NOTE: this function has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const name = "testcreateskykey";

async function getSkykeyByNameExample() {
  try {
    const skykey = await client.getSkykeyByName(name);
  } catch (error) {
    console.log(error)
  }
}

// NOTE: this function has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

const name = "testcreateskykey";

(async () => {
    const skykey = await skynet.getSkykeyByName(name);
})();

# NOTE: this function has not yet been implemented for this SDK.

import siaskynet as skynet

name = "testcreateskykey"

skykey = skynet.get_skykey_by_name(name)
print("Get skykey successful, skykey: " + skykey)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    const name = "testcreateskykey"

    fmt.Printf("Getting skykey with name %v...\n", name)
    skykey, err := skynet.GetSkykeyByName(name, skynet.DefaultGetSkykeyOptions)
    if err != nil {
        panic("Unable to get skykey: " + err.Error())
    }
    fmt.Printf("Skykey: %#v\n", skykey)

This function returns the base-64 encoded skykey stored under that name.

Parameters

Parameter	Description
`name`	Name of the skykey being queried.

Response

See Creating A Skykey.

Getting A Skykey By ID

curl -A "Sia-Agent"  -u "":<apipassword> --data "id=gi5z8cf5NWbcvPBaBn0DFQ==" "localhost:9980/skynet/skykey"

skynet skykey get id "pJAPPfWkWXpss3BvMDCJCw=="

// NOTE: this function has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const id = "pJAPPfWkWXpss3BvMDCJCw==";

async function getSkykeyByIdExample() {
  try {
    const skykey = await client.getSkykeyById(id);
  } catch (error) {
    console.log(error)
  }
}

// NOTE: this function has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

const id = "pJAPPfWkWXpss3BvMDCJCw==";

(async () => {
    const skykey = await skynet.getSkykeyById(id);
})();

# NOTE: this function has not yet been implemented for this SDK.

import siaskynet as skynet

id = "pJAPPfWkWXpss3BvMDCJCw=="

skykey = skynet.get_skykey_by_id(id)
print("Get skykey successful, skykey: " + skykey)

package main

import skynet "github.com/NebulousLabs/go-skynet"

func main() {
    const id = "pJAPPfWkWXpss3BvMDCJCw=="

    fmt.Printf("Getting skykey with id %v...\n", id)
    skykey, err := skynet.GetSkykeyByID(id, skynet.DefaultGetSkykeyOptions)
    if err != nil {
        panic("Unable to get skykey: " + err.Error())
    }
    fmt.Printf("Skykey: %#v\n", skykey)
}

This function returns the base-64 encoded skykey stored under that ID.

Parameters

Parameter	Description
`id`	ID of the skykey being queried.

Response

See Creating A Skykey.

Listing Skykeys

curl -A "Sia-Agent"  -u "":<apipassword> "localhost:9980/skynet/skykeys"

skynet skykey list

// NOTE: this function has not yet been implemented for this SDK.

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();

async function getSkykeysExample() {
  try {
    const skykeys = await client.getSkykeys();
  } catch (error) {
    console.log(error)
  }
}

// NOTE: this function has not yet been implemented for this SDK.

const skynet = require('@nebulous/skynet');

(async () => {
    const skykeys = await skynet.getSkykeys();
})();

# NOTE: this function has not yet been implemented for this SDK.

import siaskynet as skynet

skykeys = skynet.get_skykeys()
print("Get skykeys successful, skykeys: " + skykeys)

package main

import (
    "fmt"
    skynet "github.com/NebulousLabs/go-skynet"
)

func main() {
    fmt.Println("Listing skykeys...")
    skykeys, err := skynet.ListSkykeys(skynet.DefaultListSkykeysOptions)
    if err != nil {
        panic("Unable to get skykeys: " + err.Error())
    }
    fmt.Printf("Skykeys: %v\n", skykeys)
}

This function lists all skykeys on the given portal.

Parameters

None

Response

List of Skykeys (see Creating A Skykey).

Browser JS Utilities

The following are some utilities that only make sense in the browser, and thus are only provided by the Browser JS SDK.

Open

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

try {
  client.open(skylink);
} catch (error) {
  console.log(error);
}

Use the client to open a skylink in a new browser tab. Browsers support opening natively only limited file extensions like .html or .jpg and will fallback to downloading the file.

Parameters

See Downloading A File.

Response

Empty on success.

Getting The Download URL

import { SkynetClient } from "skynet-js";

const client = new SkynetClient();
const skylink = "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

try {
  const url = client.getDownloadUrl(skylink);
} catch (error) {
  console.log(error);
}

Use the client to generate a direct skylink url.

Parameters

See Downloading A File.

Additional Options

Field	Description	Default
`download`	Option to include download directive in the url that will force a download when used.	`false`

Response

"https://siasky.net/XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

Field	Description
`url`	The URL for the given skylink on the client portal.

Parsing Skylinks

import { parseSkylink } from "skynet-js";

const client = new SkynetClient();
const uri = "sia://XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg";

try {
  const skylink = parseSkylink(uri);
} catch (error) {
  console.log(error);
}

Extract a skylink from a string.

Parameters

Field	Description
`string`	The string to extract a skylink from.

Currently supported string types are:

direct skylink string, for example "XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"
sia: prefixed string, for example "sia:XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"
sia:// prefixed string, for example "sia://XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"
skylink from url, for example "https://siasky.net/XABvi7JtJbQSMAcDwnUnmp2FKDPjg8_tTTFP4BwMSxVdEg"

Response

"CABAB_1Dt0FJsxqsu_J4TodNCbCGvtFf1Uys_3EgzOlTcg"

Field	Description
`skylink`	See Uploading A File.