Skip to content

Buckets

The following endpoints allow you to get, add, edit and delete buckets in your account.

✅

Quick Tip
Your authentication token will be required to perform the following requests.
You can get your authentication token in your user account settings located in Account Settings > Authentication. You can also get your token using the API with your email and password.

Get Buckets

Gets all Buckets connected to your account.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

ParameterTypeDefaultDescription
prettyEnumfalsetrue, Makes the response more reader-friendly

Definition

GET $BASE_URL/buckets

Example Response

{
  "buckets": [
    {
      "id": "600af4e0c56e342a668b0d30",
      "slug": "bucket-added-from-api",
      "title": "Bucket added from API V2",
      "created_at": "2021-01-22T15:53:04.754Z",
      "modified_at": "2021-01-22T15:57:44.863Z",
      "api_access": {
        "write_key": "...",
        "read_key": "..."
      }
    }
  ]
}

Get Bucket

Returns bucket by slug connected to your Bucket.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

ParameterTypeDefaultDescription
prettyEnumfalsetrue, Makes the response more reader-friendly

Definition

GET $BASE_URL/buckets/${bucket_slug}

Example Response

{
  "bucket": {
    "id": "600af4e0c56e342a668b0d30",
    "slug": "bucket-added-from-api",
    "title": "Bucket added from API V2",
    "created_at": "2021-01-22T15:53:04.754Z",
    "modified_at": "2021-01-22T15:57:44.863Z",
    "api_access": {
      "write_key": "5WT161Y1Qd8fv6we7anNgA4X3ya5fX4EFcq7hYdV5QpC3EsHbh",
      "read_key": "O1eShESixXMMizLFEH1pg7kh4qwMWCqkccUJ7EIFSZOUy37YSW"
    }
  }
}

Add Bucket

Add a new bucket to your account.

title is the only required property. If no slug is present, the title will be converted to a slug. read_key & write_key will be auto-generated.

⚠

Required
token must be passed as Authorization Bearer in the header of the request.

ParameterRequiredTypeDescription
titlerequiredStringTitle of the bucket.
slugStringURL-friendly unique identifier
clusterStringAdd this Bucket to a Cluster. ID of existing Cluster
prettyEnumtrue, Makes the response more reader-friendly

Definition

POST $BASE_URL/buckets

Example Body (JSON)

{
  "title": "New Bucket"
}

Example Response

{
  "bucket": {
    "id": "600ef5162394f77404e0d447",
    "slug": "new-bucket",
    "title": "New Bucket",
    "created_at": "2021-01-25T16:43:02.477Z",
    "modified_at": "2021-01-25T16:43:02.477Z",
    "api_access": {
      "write_key": "xcnH0RKeKsCMdgavr6XySyiwZL36eTx2Q3gH9gER3J8QtniGuq",
      "read_key": "fE5cjxPSMDodKilD1t6gutaxDLjTVFl5XlgEIAg9IBAO2AZHlK"
    }
  }
}

Edit Bucket

Edit an existing bucket by slug in your account.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

ParameterTypeDefaultDescription
titleStringTitle of the bucket.
thumbnailStringMedia name. Media must be available in Bucket. See Media.
reset_api_access_keysEnumfalsetrue, reset the read_key & write_key
prettyEnumfalsetrue, Makes the response more reader-friendly

Note: At least one of the Parameters is required to process the request.

Definition

PATCH $BASE_URL/buckets/${bucket_slug}

Example Body (JSON)

{
  "reset_api_access_keys": true
}

Example Response

{
  "bucket": {
    "id": "600ef5162394f77404e0d447",
    "slug": "new-bucket",
    "title": "New Bucket",
    "created_at": "2021-01-25T16:43:02.477Z",
    "modified_at": "2021-01-25T16:46:53.226Z",
    "api_access": {
      "write_key": "fcVx2WoqyiIHffR8A0hEBaljT3ecrBubrYigJnDnXP8Cx6AeK7",
      "read_key": "vZ40FJ8wJzV2nhh9CEhniKpI6NtA4IP9uCUpPt8WgP2sxV4UpD"
    }
  }
}

Delete Bucket

Delete an existing bucket by slug from your account.

⚠

Required
token must be passed as Authorization Bearer in the header of the request and you must have admin access to perform this operation.

❗

Danger
Deletes the whole Bucket with objects, revisions, object types and media. This cannot be undone.

Definition

DELETE $BASE_URL/buckets/${bucket_slug}

Example Response

{
  "message": "Bucket with slug: '${bucket_slug}' deleted successfully.'"
}