AboutAppCrypto PaymentsHTTP API
1.8.0
OAS 3.0.0

Tusky API

Decentralized file system build on Walrus (SUI blockchain).



Authorization

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.



Pagination

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.



Error codes

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.



Request IDs

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.

API Key (api_key)
Client Libraries
cURL Shell

Files​

Same as in your local file systems, Tusky has files. Tusky's file is a pointer to Walrus blob, keeping replica of:

  • blobId - Walrus blob's unique indentifier. No two blobs on Walrus may have same blobId. You may retrieve file binary over any Walrus aggregator with your blobId.

  • storedEpoch - epoch is a unit of time in which Walrus storage nodes operate in. This attribute says when the file was stored on the network.

  • certifiedEpoch - epoch when the file was certified by the network. This is a moment when a corresponding transaction was finalized and considered valid by the Sui blockchain.

  • ref - reference SUI transaction.

  • erasureCodeType - specifies the algorithm or scheme used for encoding and distributing data in the Walrus system.

Uploading file is done by /uploads endpoint.

You may query your files by vaultId, parentId (direct parent of files, can be folder or vault) or by default owner - you.

Files Endpoints

Lists files​

This operation returns a maximum of 1000 file entries and defaults to 100 if limit is not provided. Use the limit and nextToken parameters to paginate. You can query by container using the parentId or vaultId parameters.

Query Parameters
  • limit
    integer int32

    Maximum number of files in response.

  • nextToken
    string

    Token for fetching the next set of files.

  • status
    string

    Fetch files in specific status.

    Exampleactive
  • parentId
    string

    Identifier of vault or folder - direct parent.

  • vaultId
    string

    Identifier of vault - can be indirect parent.

  • uploadId
    string

    Identifier of uploadId

Responses
GET/files
curl https://api.tusky.io/files

[
  {}
]

List of files

Models