ChainSafe Storage API (1.19.2)

Download OpenAPI specification:Download

ChainSafe: info@chainsafe.io URL: storage.chainsafe.io

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

200
404
default

Content type

application/json

[{"id": "string",
"name": "string",
"type": "csf",
"owners": [{"uuid": "string",
"encryption_key": "string"
}
],
"writers": [{"uuid": "string",
"encryption_key": "string"
}
],
"readers": [{"uuid": "string",
"encryption_key": "string"
}
],
"size": 0,
"public": "read",
"file_system_type": "chainsafe",
"status": "created"
}
]

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

Payload

Content type

application/json

{"name": "string",
"type": "csf",
"encryption_key": "string",
"file_system_type": "chainsafe",
"writers": [{"uuid": "string",
"encryption_key": "string"
}
],
"readers": [{"uuid": "string",
"encryption_key": "string"
}
],
"public": "read"
}

Response samples

200
400
404
default

Content type

application/json

{"id": "string",
"name": "string",
"type": "csf",
"owners": [{"uuid": "string",
"encryption_key": "string"
}
],
"writers": [{"uuid": "string",
"encryption_key": "string"
}
],
"readers": [{"uuid": "string",
"encryption_key": "string"
}
],
"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

200
404
default

Content type

application/json

{"id": "string",
"name": "string",
"type": "csf",
"owners": [{"uuid": "string",
"encryption_key": "string"
}
],
"writers": [{"uuid": "string",
"encryption_key": "string"
}
],
"readers": [{"uuid": "string",
"encryption_key": "string"
}
],
"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

Payload

Content type

application/json

{"name": "string",
"writers": [{"uuid": "string",
"encryption_key": "string"
}
],
"readers": [{"uuid": "string",
"encryption_key": "string"
}
],
"public": "read"
}

Response samples

404
default

Content type

application/json

{"error": {"code": 400,
"message": "example error message",
"details": [{"type": "example type",
"message": "Example message"
}
]
}
}

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

404
default

Content type

application/json

{"error": {"code": 400,
"message": "example error message",
"details": [{"type": "example type",
"message": "Example message"
}
]
}
}

Summary

Retrieves the bucket summary of the users storage account.

Authorizations:

bearerAuth

Responses

Response samples

200
404
default

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

200
404
409
503
default

Content type

application/json

{"owners": [{"id": "string",
"uuid": "string",
"username": "not-greg123",
"identity_pubkey": "0x0000000096216849C49358B10257CB55B28EA603C8000000000000000000C0FFEE",
"public_address": "0X96216849C49358B10257CB55B28EA603C8C0FFEE"
}
],
"writers": [{"id": "string",
"uuid": "string",
"username": "not-greg123",
"identity_pubkey": "0x0000000096216849C49358B10257CB55B28EA603C8000000000000000000C0FFEE",
"public_address": "0X96216849C49358B10257CB55B28EA603C8C0FFEE"
}
],
"readers": [{"id": "string",
"uuid": "string",
"username": "not-greg123",
"identity_pubkey": "0x0000000096216849C49358B10257CB55B28EA603C8000000000000000000C0FFEE",
"public_address": "0X96216849C49358B10257CB55B28EA603C8C0FFEE"
}
]
}

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

Payload

Content type

application/json

{"is_update": false,
"files_meta": [{"path": "home/chainsafe/abc.txt"
}
]
}

Response samples

200
404
503
default

Content type

application/json

{"status": "success",
"files_details": [{"path": "home/chainsafe/abc.txt",
"cid": "string",
"type": "application/json",
"size": 0,
"status": "failed",
"error_code": 409,
"message": "entry already exists, cannot add",
"suggestion": "home/chainsafe/abc(1).txt"
}
]
}

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

200
404
409
503
default

Content type

application/json

{"path": "string",
"files_details": [{"path": "home/chainsafe/abc.txt",
"cid": "string",
"type": "application/json",
"size": 0,
"status": "failed",
"error_code": 409,
"message": "entry already exists, cannot add",
"suggestion": "home/chainsafe/abc(1).txt"
}
]
}

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

200
404
409
503
default

Content type

application/json

{"path": "string",
"files_details": [{"path": "home/chainsafe/abc.txt",
"cid": "string",
"type": "application/json",
"size": 0,
"status": "failed",
"error_code": 409,
"message": "entry already exists, cannot add",
"suggestion": "home/chainsafe/abc(1).txt"
}
]
}

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

Payload

Content type

application/json

{"path": "string"
}

Response samples

400
404
503
default

Content type

application/json

{"error": {"code": 400,
"message": "example error message",
"details": [{"type": "example type",
"message": "Example message"
}
]
}
}

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

Payload

Content type

application/json

{"paths": ["string"
],
"new_path": "string",
"destination": "string"
}

Response samples

404
409
503
default

Content type

application/json

{"error": {"code": 400,
"message": "example error message",
"details": [{"type": "example type",
"message": "Example message"
}
]
}
}

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

Payload

Content type

application/json

{"path": "string"
}

Response samples

200
400
503
default

Content type

application/json

{"content": {"name": "file1.pdf",
"cid": "cid1",
"size": 0,
"content_type": "pdf",
"version": 1,
"created_at": 0
},
"persistent": {"uploaded": 0,
"saved_time": 0,
"stored_size": 0,
"stored_cid": "string",
"filecoin": {"cid": "string",
"size": 0,
"proposals": [{"cid": "string",
"duration": 0,
"activation_epoch": 0,
"start_epoch": 0,
"miner": "string",
"epoch_price": 0
}
]
}
},
"messages": ["string"
]
}

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

Payload

Content type

application/json

{"paths": ["string"
]
}

Response samples

404
503
default

Content type

application/json

{"error": {"code": 400,
"message": "example error message",
"details": [{"type": "example type",
"message": "Example message"
}
]
}
}

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

Payload

Content type

application/json

{"path": "string"
}

Response samples

200
404
503
default

Content type

application/json

[{"name": "file1.pdf",
"cid": "cid1",
"size": 0,
"content_type": "pdf",
"version": 1,
"created_at": 0
}
]

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

Payload

Content type

application/json

{"path": "string"
}

Response samples

200
404
409
503
default

Content type

application/json

{"name": "file1.pdf",
"cid": "cid1",
"size": 0,
"content_type": "pdf",
"version": 1,
"created_at": 0
}