Buckets

Bucket is the central object in the platform. You can think of each Bucket as a separate SFTP server in which you can create users, directories, add webhooks, and more. A logical application would be to create one Bucket for each customer you work with to keep data separated.

The Bucket Model

The Bucket model contains all the information about the buckets you have created.

Properties

Name
id
Type
string
Description
Unique identifier for the bucket.
Name
host
Type
string
Description
The host for the bucket. This can be provided to your customers for SFTP connectivity.
Name
name
Type
string
Description
The human-readable name for the bucket.
Name
active
Type
boolean
Description
Whether or not the bucket is active and accepting connections/files.
Name
created_at
Type
timestamp
Description
Unix Timestamp of when the bucket was created.

POST/v1/buckets

Create a Bucket

Use this route to create a new Bucket in your account.

Request

{
  "name": "Acme Corporation Bucket"
}

Response

{
  "id": "bio_test_buc_1amaj5125as",
  "name": "Acme Corporation Bucket",
  "host": "1amaj5125as.sftp.usebuckets.io",
  "active": true,
  "created_at": 692233200
}

GET/v1/buckets

Fetch All Buckets

Use this route to fetch the buckets attached to your current API key.

Request

GET

/v1/buckets

curl -X GET https://api.usebuckets.io/v1/buckets \
  -H "Authorization: Bearer {token}"

Response

{
    "has_more": true,
    "next_uri": "/v1/buckets?after=bio_test_buc_8gkde9034zx",
    "data": [
        {
            "id": "bio_test_buc_1amaj5125as",
            "name": "Acme Corporation Bucket",
            "host": "1amaj5125as.sftp.usebuckets.io",
            "active": true,
            "created_at": 692233200
        },
        {
            "id": "bio_test_buc_8gkde9034zx",
            "name": "Example Organization Bucket",
            "host": "8gkde9034zx.sftp.usebuckets.io",
            "active": true,
            "created_at": 692233200
        }
    ]
}

PATCH/v1/buckets/{bucket_id}

Update a Bucket

Use this route to update the name or active status of a Bucket. You must include at least one of those properties for the call to be successful.

Request

{
  "name": "Updated Name"
}

Response

{
  "id": "bio_test_buc_1amaj5125as",
  "name": "Updated Name",
  "host": "1amaj5125as.sftp.usebuckets.io",
  "active": true,
  "created_at": 692233200
}

DELETE/v1/buckets/{bucket_id}

Delete a Bucket

Use this route when you want to fully delete a bucket, its contents, and its users. This action is not reversible. You can turn off API bucket deletion inside of your account settings to prevent any calls to this route from succeeding.

Response

HTTP 200