> For the complete documentation index, see [llms.txt](https://docs.apolo.us/index/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apolo.us/index/apolo-mcp/capabilities/tools/buckets.md).

# Buckets

[Back to the MCP tool reference](/index/apolo-mcp/capabilities/tools.md).

## `list_buckets`

List bucket metadata under a strict result bound.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "title": "list_bucketsArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "list_bucketsDictOutput",
  "type": "object"
}
```

## `get_bucket`

Get safe metadata for one exact bucket ID or name.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "bucket_id_or_name": {
      "title": "Bucket Id Or Name",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "bucket_id_or_name"
  ],
  "title": "get_bucketArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "get_bucketDictOutput",
  "type": "object"
}
```

## `create_bucket`

Create and ledger a bucket after policy and client approval.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "title": "create_bucketArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "create_bucketDictOutput",
  "type": "object"
}
```

## `import_external_bucket`

Import using bounded JSON credentials from a protected internal source.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "credential_source_name": {
      "title": "Credential Source Name",
      "type": "string"
    },
    "credential_source_type": {
      "enum": [
        "env",
        "file",
        "secret"
      ],
      "title": "Credential Source Type",
      "type": "string"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Name"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "provider": {
      "enum": [
        "aws",
        "minio",
        "azure",
        "gcp",
        "open_stack"
      ],
      "title": "Provider",
      "type": "string"
    },
    "provider_bucket_name": {
      "title": "Provider Bucket Name",
      "type": "string"
    }
  },
  "required": [
    "provider",
    "provider_bucket_name",
    "credential_source_type",
    "credential_source_name"
  ],
  "title": "import_external_bucketArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "import_external_bucketDictOutput",
  "type": "object"
}
```

## `get_bucket_disk_usage`

Scan bounded usage; complete=false means the object cap was reached.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "bucket_id_or_name": {
      "title": "Bucket Id Or Name",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "max_objects": {
      "default": 10000,
      "title": "Max Objects",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 60.0,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "bucket_id_or_name"
  ],
  "title": "get_bucket_disk_usageArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "get_bucket_disk_usageDictOutput",
  "type": "object"
}
```

## `stat_bucket_blob`

Return metadata only for one exact blob key.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "bucket_id_or_name": {
      "title": "Bucket Id Or Name",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "bucket_id_or_name",
    "key"
  ],
  "title": "stat_bucket_blobArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "stat_bucket_blobDictOutput",
  "type": "object"
}
```

## `list_bucket_blobs`

List blob metadata under an SDK-enforced and result-enforced bound.

**Operation type:** read-only

**Annotations:** read-only `true`, destructive `false`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "bucket_id_or_name": {
      "title": "Bucket Id Or Name",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "prefix": {
      "default": "",
      "title": "Prefix",
      "type": "string"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "recursive": {
      "default": false,
      "title": "Recursive",
      "type": "boolean"
    }
  },
  "required": [
    "bucket_id_or_name"
  ],
  "title": "list_bucket_blobsArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "list_bucket_blobsDictOutput",
  "type": "object"
}
```

## `set_bucket_public_access`

Set public state for one exact immutable bucket ID.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "bucket_id": {
      "title": "Bucket Id",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "public": {
      "title": "Public",
      "type": "boolean"
    }
  },
  "required": [
    "bucket_id",
    "public"
  ],
  "title": "set_bucket_public_accessArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "set_bucket_public_accessDictOutput",
  "type": "object"
}
```

## `create_bucket_signed_url`

Create a short-lived blob URL; no persistent credentials are returned.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "bucket_id": {
      "title": "Bucket Id",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "destination_file": {
      "title": "Destination File",
      "type": "string"
    },
    "expires_in_seconds": {
      "default": 900,
      "title": "Expires In Seconds",
      "type": "integer"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "bucket_id",
    "key",
    "destination_file"
  ],
  "title": "create_bucket_signed_urlArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "create_bucket_signed_urlDictOutput",
  "type": "object"
}
```

## `upload_bucket_file`

Upload one bounded workspace file without serializing object bytes.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "bucket_id": {
      "title": "Bucket Id",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "local_path": {
      "title": "Local Path",
      "type": "string"
    },
    "max_bytes": {
      "default": 1073741824,
      "title": "Max Bytes",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 300.0,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "local_path",
    "bucket_id",
    "key"
  ],
  "title": "upload_bucket_fileArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "upload_bucket_fileDictOutput",
  "type": "object"
}
```

## `download_bucket_file`

Download one bounded blob to a new file below the workspace root.

**Operation type:** write

**Annotations:** read-only `false`, destructive `false`, idempotent `false`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "bucket_id": {
      "title": "Bucket Id",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "local_path": {
      "title": "Local Path",
      "type": "string"
    },
    "max_bytes": {
      "default": 1073741824,
      "title": "Max Bytes",
      "type": "integer"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    },
    "timeout_seconds": {
      "default": 300.0,
      "title": "Timeout Seconds",
      "type": "number"
    }
  },
  "required": [
    "bucket_id",
    "key",
    "local_path"
  ],
  "title": "download_bucket_fileArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "download_bucket_fileDictOutput",
  "type": "object"
}
```

## `delete_bucket_blob`

Delete one exact blob key; recursive/prefix deletion is not exposed.

**Operation type:** destructive

**Annotations:** read-only `false`, destructive `true`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "bucket_id": {
      "title": "Bucket Id",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "bucket_id",
    "key"
  ],
  "title": "delete_bucket_blobArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "delete_bucket_blobDictOutput",
  "type": "object"
}
```

## `delete_bucket`

Delete one exact empty bucket ID, optionally as ledger-owned cleanup.

**Operation type:** destructive

**Annotations:** read-only `false`, destructive `true`, idempotent `true`, open-world `true`

**Input schema:**

```json
{
  "properties": {
    "approved": {
      "default": false,
      "title": "Approved",
      "type": "boolean"
    },
    "automatic_cleanup": {
      "default": false,
      "title": "Automatic Cleanup",
      "type": "boolean"
    },
    "bucket_id": {
      "title": "Bucket Id",
      "type": "string"
    },
    "cluster": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Cluster"
    },
    "org": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Org"
    },
    "project": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Project"
    }
  },
  "required": [
    "bucket_id"
  ],
  "title": "delete_bucketArguments",
  "type": "object"
}
```

**Output schema:**

```json
{
  "additionalProperties": true,
  "title": "delete_bucketDictOutput",
  "type": "object"
}
```