---
title: Create a bucket
description: Creates a bucket and returns it when it is active.
doc_version: 0.1.0-preview
last_updated: 2026-09-14
---

# Create a bucket

`POST /v1/workspaces/{workspaceId}/buckets`

Creates a bucket and returns it when it is active. Provider, location, and indexing are fixed when the bucket is created. A request that omits them gets gcp, the US multi-region, and indexing enabled. Tell the user which provider and location the bucket uses, and that other values are available. Role: editor or higher.

## Authentication

Send `Authorization: Bearer <GRAPHON_API_KEY>`. Read the key from the
GRAPHON_API_KEY environment variable. Never print it.

## Path parameters

- `workspaceId` (string) — The workspace id.

## Request body

- `name` (string) — A case-sensitive name unique within this workspace. Use 1 to 255 ASCII letters, digits, periods, underscores, or hyphens. The exact names . and .. are invalid.
- `provider` (string (optional)) — gcp or r2. The default is gcp. It is fixed when the bucket is created.
- `location` (string (optional)) — The provider region, for example us-central1. The default is the US multi-region of the provider. It is fixed when the bucket is created.
- `indexing` (string (optional)) — Whether Graphon indexes the objects so that you can search and query them. Fixed when the bucket is created. One of: enabled, disabled.
- `storageClass` (string (optional)) — The storage class. The default is standard.
- `permission` (string (optional)) — Who can read objects: private, or public-read for anonymous GET and HEAD. One of: private, public-read.
- `policy` (object (optional)) — Bucket policy settings.

## Example request

```bash
curl \
  --url "https://storage.graphon.sh/v1/workspaces/wspq7ws2np5l8z4/buckets" \
  --header "Authorization: Bearer $GRAPHON_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"name":"support-tickets","provider":"gcp","location":"us-central1","indexing":"enabled"}'
```

## CLI

```bash
graphon buckets create support-tickets
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.