Tusky API

Decentralized file system build on Walrus (SUI blockchain).

Tusky authenticates your API requests using your account’s API keys. If a request doesn’t include a valid key or it includes a deleted or expired key, Tusky returns an HTTP 401 status.

Use the Tusky App to create or delete your API keys. To access your API keys, select the API Keys tab in your Account.

Some top-level API resources have support for bulk fetches through HTTP GET API requests. For example, you can list file system entities: vaults, folders, files. These list API methods share a common structure and accept, the following parameters: limit, nextToken. Response structure is same for those paginated methods, containing two top-level attributes: items, nextToken.

Both parameters are optional. Omitted limit defaults to 100. Omitted nextToken defaults to first “page” with default API method’s sort considered.

Tusky’s paginated API methods use cursor-based pagination through the nextToken parameter. This means you can only go to the next “page” of items, not to the previous.

For example fetching files in folder would go like: GET /files?parentId=xyz

Such HTTP call is requesting first 100 (default limit) files which are contained in folder with identifier equal to xyz. Response to such request will contain JSON body with:

• items: list of sorted (by default sort key = updatedAt) file entries, possibly empty if no files found in given folder.

• nextToken: next page cursor, possibly empty if there are less than 100 files in xyz folder.

Tusky uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

• codes in the 2xx range indicate success.

• codes in the 4xx range indicate client side error - missing or invalid parameter (e.g. trying to delete vault that is not empty; trying to permanently delete folder that is not in trash).

• codes in the 5xx range indicate an error with Tusky’s servers - these are rare, retryable and can be reported to Tusky’s support.

Each API request has an associated request identifier. You can find this value in the response headers, under Request-Id.

In case of any issues encountered, to speed up the resolution process, provide the request identifier when you contact us about a specific request.

Here is how you can upload files to Tusky:

First, setup your account at https://app.tusky.io & generate API key

Then create vault:

const response = await fetch('https://api.tusky.io/vaults', {
  method: 'POST',
  headers: {
    'Api-Key': 'YOUR_API_KEY',
  },
  body: {
    name: 'Vaulty vault',
  },
});

const vault = await response.json();

Ready to upload files!

Tusky implements tus.io - a magnificent HTTP protocol for resumable file uploads. There are many SDKs out there, both officially supported by tus.io and from community. We recommend using one of those.

npm i tus-js-client

const fileStats = fs.statSync('YOUR_FILE_PATH');
const fileSize = fileStats.size;
const fileName = filePath.split('/').pop();
const fileStream = fs.createReadStream(filePath);

const upload = new tus.Upload(fileStream, {
  endpoint: endpoint,
  headers: {
    'Api-Key': 'YOUR_API_KEY',
  },
  metadata: {
    filename: fileName,
    filetype: 'text/plain', // Adjust according to your file type
    vaultId: vault.id,
  },
  onError: error => {
    console.error('Upload failed:', error.message);
  },
  onProgress: (bytesUploaded, bytesTotal) => {
    const percentage = ((bytesUploaded / bytesTotal) * 100).toFixed(2);
    console.log(`Progress: ${percentage}% (${bytesUploaded}/${bytesTotal} bytes)`);
  },
  onSuccess: () => {
    console.log('Upload completed successfully!');
  },
});

upload.start();