Skip to main content

Storage API

API docs by Redocly

ChainSafe Storage API (1.19.3)

Download OpenAPI specification:Download

ChainSafe: info@chainsafe.io URL: storage.chainsafe.io
Find out more about ChainSafe

Bucket Management

This section contains API references for Bucket Management. This provides set of APIs to manage buckets and access control in ChainSafe Storage.

List buckets

Returns a list of all buckets owned by the user

Authorizations:
bearerAuth
query Parameters
type
Array of strings (BucketTypeList)
Items Enum: "csf" "fps" "trash" "pinning" "share" "nft"

filter on the type of the bucket

public_access
Array of strings (BucketPublicTypeList)
Items Enum: "read" "write"

filter on the access type of the bucket

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create bucket

Creates a new bucket. User creating the bucket becomes the owner of it.

Authorizations:
bearerAuth
Request Body schema: application/json

information to update pin

name
required
string

name of the bucket

type
required
string (BucketType)
Enum: "csf" "fps" "trash" "pinning" "share" "nft"

type of bucket. Use fps for ChainSafe Storage bucket

encryption_key
string

User's symmetric encryption phrase encrypted with user's tKey public key (required for share bucket)

file_system_type
string or null (FileSystemType)
Enum: "chainsafe" "ipfs" null

Filesystem to be used for the bucket.

Array of objects (BucketUser)

list of id of users

Array of objects (BucketUser)

list of id of users

public
string (BucketPublicType)
Enum: "read" "write"

this parameter defines public access type of the bucket.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "csf",
  • "encryption_key": "string",
  • "file_system_type": "chainsafe",
  • "writers": [
    ],
  • "readers": [
    ],
  • "public": "read"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "csf",
  • "owners": [
    ],
  • "writers": [
    ],
  • "readers": [
    ],
  • "size": 0,
  • "public": "read",
  • "file_system_type": "chainsafe",
  • "status": "created"
}

Get bucket

Retrieves a bucket information owned by the user.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "csf",
  • "owners": [
    ],
  • "writers": [
    ],
  • "readers": [
    ],
  • "size": 0,
  • "public": "read",
  • "file_system_type": "chainsafe",
  • "status": "created"
}

Update bucket

Update bucket details.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

Updated Bucket details. Only Name and Access control list can be for the bucket can be updated

name
string

bucket name

Array of objects (BucketUser)

list of id of users

Array of objects (BucketUser)

list of id of users

public
string (BucketPublicType)
Enum: "read" "write"

this parameter defines public access type of the bucket.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "writers": [
    ],
  • "readers": [
    ],
  • "public": "read"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Delete bucket

Deletes the bucket including all objects in the bucket.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Summary

Retrieves the bucket summary of the users storage account.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "total_buckets": 0,
  • "available_storage": 0,
  • "total_storage": 0,
  • "used_storage": null
}

Bucket users

returns buckets users with additional information about the user

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Responses

Response samples

Content type
application/json
{
  • "owners": [
    ],
  • "writers": [
    ],
  • "readers": [
    ]
}

Object Management

This section contains API references for Object Management. This provides set of APIs to upload, donwload and manage objects in the ChainSafe Storage Bucket.

Pre-upload Check

The API runs pre-upload checks based on the files details provided and return error that could be encountered during upload.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

files details containing paths

is_update
required
boolean

Perform pre-check for the update object request

required
Array of objects (PreUploadRequestItem)

Array of full file paths to be uploaded.The endpoint checks for any file-system conflicts

Responses

Request samples

Content type
application/json
{
  • "is_update": false,
  • "files_meta": [
    ]
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "files_details": [
    ]
}

Upload Objects

uploads one or more files to the bucket. The user must have write access to the bucket.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: multipart/form-data

attributes of file to upload

file
required
Array of strings <binary>

array of files that needs to be uploaded

path
required
string

path in bucket's file system where uploaded objects will be placed

Responses

Response samples

Content type
application/json
{
  • "path": "string",
  • "files_details": [
    ]
}

Update

Updates a one or more files on the bucket. The user must have write access to the bucket.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string

bucket identifier

Request Body schema: multipart/form-data

attributes of file to update

file
Array of strings <binary>

array of files that needs to be updated

path
required
string or null

path in user's file system where uploaded objects will be placed

Responses

Response samples

Content type
application/json
{
  • "path": "string",
  • "files_details": [
    ]
}

Upload NFT Metadata

Upload NFT Metadata & related binary files

Authorizations:
bearerAuth
query Parameters
hash
string
Enum: "identity" "sha1" "sha2-256" "sha2-512" "sha3" "sha3-224" "sha3-256" "sha3-384" "sha3-512" "keccak-224" "keccak-256" "keccak-384" "keccak-512" "blake2b-n.8 (1<=n<=64)" "blake2s-n.8 (1<=n<=32)" "dbl-sha2-256" "murmur3-x64-64" "blake3" "shake-128" "shake-256" "sha2-256-trunc254-padded" "x11" "md5" "poseidon-bls12_381-a2-fc1" "blake2b-208"

-> The hash function to use on generating cid that will be returned on response. If invalid or no option provided it will use default hash(sha2-256).

Request Body schema: multipart/form-data

NFT Data to be uploaded

object

Responses

Response samples

Content type
application/json
{
  • "cid": "string"
}

Download Object

Retrieve content of file stored in a bucket. The user must have read access to the bucket.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

file path

path
required
string

path to the file object

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Move Objects

Move or rename files in the bucket. The user must have write access to the bucket.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json
paths
required
Array of strings

list of paths to be moved

new_path
required
string

desired new path file object needs to be moved

destination
string (BucketID)

unique bucket identifier

Responses

Request samples

Content type
application/json
{
  • "paths": [
    ],
  • "new_path": "string",
  • "destination": "string"
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

Object Info

Retrieves all information available on a file

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

file path

path
required
string

path to the file object

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "content": {
    },
  • "persistent": {
    },
  • "messages": [
    ]
}

Delete Objects

removes a files or directories from the bucket

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

array of object paths

paths
required
Array of strings

list of paths to the file objects that needs to be deleted

Responses

Request samples

Content type
application/json
{
  • "paths": [
    ]
}

Response samples

Content type
application/json
{
  • "error": {
    }
}

List Objects

Retrieve child list for provided directory path

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

file path

path
required
string

path to the file object

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
[
  • {
    }
]

Create Folder

Creates a new folder on the bucket.

Authorizations:
bearerAuth
path Parameters
bucket_id
required
string (BucketID)

unique bucket identifier

Request Body schema: application/json

directory path

path
required
string

path to the file object

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "name": "file1.pdf",
  • "cid": "cid1",
  • "size": 0,
  • "content_type": "pdf",
  • "version": 1,
  • "created_at": 0
}