[dev 🤫] Basic bucket API - not meant to be merged

[Wauplin]

Currently only for debug/tests purposes. Mimics server API. In practice we would refactor some logic, move parts to a _bucket.py module, create a high-level interface, build a CLI, etc. Not in the scope for this PR.

Related to (private) PR in moon-landing https://github.com/huggingface-internal/moon-landing/pull/16332

---

How to use

1. Run moon-landing locally
2. create token from julien-c dev account
3. edit token in bucket.py and run python bucket.py

Result

# Create bucket
{'url': 'http://localhost:5564/buckets/julien-c/test-bucket', 'id': 'julien-c/test-bucket'}

# Get bucket info
{'_id': '6965188fecba71a9f1808186', 'id': 'julien-c/test-bucket', 'private': False, 'createdAt': '2026-01-12T15:51:43.113Z', 'lastModified': '2026-01-12T15:51:43.113Z', 'usedStorage': 0}

# List buckets (non-empty)
[{'_id': '6965188fecba71a9f1808186', 'id': 'julien-c/test-bucket', 'private': False, 'createdAt': '2026-01-12T15:51:43.113Z', 'lastModified': '2026-01-12T15:51:43.113Z'}]

# Delete bucket
None

# List buckets (empty)
[]

# Create private bucket
{'url': 'http://localhost:5564/buckets/julien-c/test-bucket-private', 'id': 'julien-c/test-bucket-private'}

# Get private bucket info (with token)
{'_id': '6965188fecba71a9f1808187', 'id': 'julien-c/test-bucket-private', 'private': True, 'createdAt': '2026-01-12T15:51:43.788Z', 'lastModified': '2026-01-12T15:51:43.788Z', 'usedStorage': 0}

# Get private bucket info (without token)
Client error '401 Unauthorized' for url 'http://localhost:5173/api/buckets/julien-c/test-bucket-private' (Request ID: b917cfc2-4aab-4b9a-950e-e0c5da4d919a)
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401

Invalid username or password.

# Create bucket again
{'url': 'http://localhost:5564/buckets/julien-c/test-bucket-with-files', 'id': 'julien-c/test-bucket-with-files'}

# List bucket tree (empty)
[]

# Upload file to bucket
Processing Files (10 / 10)    : |                                                                             | 1.00MB /  0.00B,  0.00B/s  
New Data Upload               : |                                                                             | 1.00MB /  0.00B,  0.00B/s  
  ...2n/6L9bUWqMy1.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/KF47VS1Ozw.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/MGlDjUdpWu.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/LzQJu9hkj0.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/InR5SzdyEI.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/JWkxdmATZj.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/wxl3GtzPb1.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/WKoHe81oUQ.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/wrZDuHJQmF.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
  ...2n/Hlg3UNg7Yg.safetensors: 100%|█████████████████████████████████████████████████████████████████████████|  100kB /  100kB            
{'success': True}

# List bucket tree (with files)
Found 10 objects in bucket: ['6L9bUWqMy1.safetensors', 'Hlg3UNg7Yg.safetensors', 'InR5SzdyEI.safetensors', 'JWkxdmATZj.safetensors', 'KF47VS1Ozw.safetensors', 'LzQJu9hkj0.safetensors', 'MGlDjUdpWu.safetensors', 'WKoHe81oUQ.safetensors', 'wrZDuHJQmF.safetensors', 'wxl3GtzPb1.safetensors']

# Head bucket /resolve 6L9bUWqMy1.safetensors
{'vary': 'Origin', 'x-powered-by': 'huggingface-moon', 'x-request-id': '0657d9c3-7843-4b03-9ab8-22edd0740cee', 'ratelimit': '"pages";r=993;t=132', 'ratelimit-policy': '"fixed window";"pages";q=1000;w=300', 'cross-origin-opener-policy': 'same-origin', 'referrer-policy': 'strict-origin-when-cross-origin', 'content-length': '100021', 'etag': '"b0d634d8b8a77efed761adaa2512ffc973cdccbc39da7dc0251343709645368e"', 'x-xet-hash': 'b0d634d8b8a77efed761adaa2512ffc973cdccbc39da7dc0251343709645368e', 'last-modified': 'Mon, 12 Jan 2026 15:51:44 GMT', 'link': '<http://localhost:5564/api/buckets/julien-c/test-bucket-with-files/xet-read-token/latest>; rel="xet-auth", <http://localhost:4884/v1/reconstructions/b0d634d8b8a77efed761adaa2512ffc973cdccbc39da7dc0251343709645368e>; rel="xet-reconstruction-info"', 'date': 'Mon, 12 Jan 2026 15:51:45 GMT', 'connection': 'close'}

# Delete first 3 files
{'success': True}

# Head bucket /resolve 6L9bUWqMy1.safetensors (doesn't exist anymore)
Client error '404 Not Found' for url 'http://localhost:5173/buckets/julien-c/test-bucket-with-files/resolve/latest/6L9bUWqMy1.safetensors' (Request ID: feeabb4f-67c1-4803-81cf-682e64da2d14)
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404

File not found

# List bucket tree (with files)
Found 7 objects in bucket: ['JWkxdmATZj.safetensors', 'KF47VS1Ozw.safetensors', 'LzQJu9hkj0.safetensors', 'MGlDjUdpWu.safetensors', 'WKoHe81oUQ.safetensors', 'wrZDuHJQmF.safetensors', 'wxl3GtzPb1.safetensors']

# Download file JWkxdmATZj.safetensors from bucket
TODO: doesn't work in local... (downloading a newly uploaded Xet file doesn't work, both from a model or bucket)

[bot-ci-comment]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.