---
title: "Create bucket"
method: POST
path: "/api/buckets/{namespace}/{repo}"
tags: ["buckets"]
---

# Create bucket

`POST /api/buckets/{namespace}/{repo}`

## Path parameters

- `namespace` string, required
- `repo` string, required

## Request body

- object — Bucket creation options
  - `private` boolean, nullable — Bucket visibility. Defaults to public
  - `resourceGroupId` string
  - `cdn` object[] — CDN pre-warming regions
    - `provider` 'gcp' | 'aws', required
    - `region` 'us' | 'eu', required
  - `region` 'us' | 'eu' — The region where the bucket is hosted.
  - `container` boolean — Create a container (Docker image) repository usable with the HF container registry.

## Response `200`

Bucket created, url is given

- object
  - `url` string, required
  - `name` string, required
  - `id` string, required — A hex string of 24 characters representing an ObjectId.

## Other responses

- `409` — Bucket already exists, url is given

## Changes

- **2026-09-09** `d91f6b18c721` — 1 info
  - added the new optional request property `container`
- **2026-09-08** `bd17546f47b8` — 4 breaking, 1 info
  - request property `private` list-of-types was narrowed by removing types `null` from media type `application/json`
  - the `cdn/items/provider` request property type changed from no type to `string`
  - the `cdn/items/region` request property type changed from no type to `string`
  - the `region` request property type changed from no type to `string`
  - …1 more

[Change history](https://skmtc.dev/huggingface/apis/hub-api-endpoints/changes/api/buckets/:namespace/:repo/post.md)

---

[API](https://skmtc.dev/huggingface/apis/hub-api-endpoints.md) · [All operations](https://skmtc.dev/huggingface/apis/hub-api-endpoints/llms.txt) · [OpenAPI document](https://skmtc.dev/huggingface/apis/hub-api-endpoints/revisions/68387ea03846?raw)