Git-free storage buckets for files, powered by Xet. Buckets provide simple file storage without git versioning.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/hugging-face-transformers-buckets-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.1.0
info:
title: Hub API Endpoints agentic-provisioning buckets API
version: 0.0.1
description: 'We have open endpoints that you can use to retrieve information from the Hub as well as perform certain actions such as creating model, dataset or Space repos. We offer a wrapper Python client, [`huggingface_hub`](https://github.com/huggingface/huggingface_hub), and a JS client, [`huggingface.js`](https://github.com/huggingface/huggingface.js), that allow easy access to these endpoints. We also provide [webhooks](https://huggingface.co/docs/hub/webhooks) to receive real-time incremental info about repos. Enjoy!
The base URL for those endpoints below is `https://huggingface.co`. For example, to construct the `/api/models` call below, one can call the URL [https://huggingface.co/api/models](https://huggingface.co/api/models).
If you''re an Agent, you might prefer the [markdown version OpenAPI spec](https://huggingface.co/.well-known/openapi.md).
'
servers:
- url: https://huggingface.co
description: Hub
security:
- bearerAuth: []
tags:
- name: buckets
x-displayName: Buckets
description: Git-free storage buckets for files, powered by Xet. Buckets provide simple file storage without git versioning.
paths:
/api/buckets/{namespace}/{repo}/lfs-files/duplicate:
post:
description: Duplicate xet-stored files from this repo (source) into another repo (target) by xet hash, without re-uploading file bytes. The caller must then commit the files with their sha256/size as usual.
summary: Duplicate xet files
tags:
- buckets
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
target:
type: object
properties:
type:
enum:
- dataset
- model
- space
- kernel
name:
type: string
minLength: 1
required:
- type
- name
files:
minItems: 1
maxItems: 1000
type: array
items:
type: object
properties:
xetHash:
type: string
minLength: 64
maxLength: 64
pattern: ^[0-9a-fA-F]{64}$
sha256:
type: string
minLength: 64
maxLength: 64
pattern: ^[0-9a-fA-F]{64}$
filename:
type: string
maxLength: 1000
required:
- xetHash
- sha256
required:
- target
- files
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
success:
description: True if all requested files were duplicated (or already present)
type: boolean
processed:
description: Total number of unique files processed
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
succeeded:
description: Number of files duplicated or already present in the target
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
failed:
description: Per-file failures
type: array
items:
type: object
properties:
xetHash:
description: Xet content hash of the file that failed
type: string
sha256:
description: sha256 of the file that failed
type: string
error:
description: Error message
type: string
required:
- xetHash
- sha256
- error
additionalProperties: false
required:
- success
- processed
- succeeded
- failed
additionalProperties: false
description: Duplicate xet files response
'207':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
success:
description: True if all requested files were duplicated (or already present)
type: boolean
processed:
description: Total number of unique files processed
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
succeeded:
description: Number of files duplicated or already present in the target
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
failed:
description: Per-file failures
type: array
items:
type: object
properties:
xetHash:
description: Xet content hash of the file that failed
type: string
sha256:
description: sha256 of the file that failed
type: string
error:
description: Error message
type: string
required:
- xetHash
- sha256
- error
additionalProperties: false
required:
- success
- processed
- succeeded
- failed
additionalProperties: false
description: Duplicate xet files response
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/buckets/{namespace}/{repo}/xet-write-token:
get:
description: Get a write short-lived access token for XET upload
summary: Xet write token
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
casUrl:
type: string
exp:
type: number
accessToken:
type: string
required:
- casUrl
- exp
- accessToken
additionalProperties: false
description: The response from the getXetWriteAccessToken endpoint.
headers:
X-Xet-Cas-Url:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
X-Xet-Token-Expiration:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
X-Xet-Access-Token:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/buckets/{namespace}/{repo}/xet-read-token:
get:
description: Get a read short-lived access token for XET
summary: Xet read token
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
casUrl:
type: string
exp:
type: number
accessToken:
type: string
required:
- casUrl
- exp
- accessToken
additionalProperties: false
description: The response from the getXetReadAccessToken endpoint.
headers:
X-Xet-Cas-Url:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
X-Xet-Token-Expiration:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
X-Xet-Access-Token:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/buckets/{namespace}/{repo}/resource-group:
post:
description: Add the repository to a resource group
summary: Add resource group
tags:
- buckets
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
resourceGroupId:
description: The resource group to add the repository to, if null, the repository will be removed from the resource group
anyOf:
- type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
- type: 'null'
required:
- resourceGroupId
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
name:
type: string
type:
enum:
- dataset
- model
- space
- bucket
- kernel
private:
type: boolean
addedBy:
type: string
required:
- name
- type
- private
- addedBy
additionalProperties: false
description: Minimal information about the repository
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
get:
summary: Get resource group
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
numUsers:
type: number
required:
- id
- name
additionalProperties: false
description: The resource group of the repository
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/buckets/{namespace}/{repo}:
post:
summary: Create bucket
tags:
- buckets
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Bucket creation options
type: object
properties:
private:
description: Bucket visibility. Defaults to public
anyOf:
- type: boolean
- type: 'null'
resourceGroupId:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-fA-F]{24}$
cdn:
description: CDN pre-warming regions
type: array
items:
type: object
properties:
provider:
enum:
- gcp
- aws
region:
enum:
- us
- eu
required:
- provider
- region
region:
description: The region where the bucket is hosted.
enum:
- us
- eu
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
url:
type: string
name:
type: string
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
required:
- url
- name
- id
additionalProperties: false
description: Bucket created, url is given
'409':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: string
url:
type: string
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
required:
- error
- url
- id
additionalProperties: false
description: Bucket already exists, url is given
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
delete:
summary: Delete bucket
tags:
- buckets
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
get:
summary: Get bucket details
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
author:
type: string
id:
type: string
private:
anyOf:
- type: boolean
- type: 'null'
createdAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
updatedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
size:
description: The amount of storage used by the bucket in bytes
type: number
totalFiles:
description: The total number of files in the bucket
type: number
repoType:
const: bucket
cdnRegions:
type: array
items:
type: object
properties:
provider:
enum:
- gcp
- aws
region:
enum:
- us
- eu
required:
- provider
- region
additionalProperties: false
resourceGroup:
type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
numUsers:
type: number
required:
- id
- name
additionalProperties: false
required:
- _id
- author
- id
- createdAt
- updatedAt
- size
- totalFiles
- repoType
- cdnRegions
additionalProperties: false
description: Bucket overview information
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/buckets/{namespace}/{repo}/settings:
put:
summary: Update bucket settings
tags:
- buckets
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
private:
anyOf:
- type: boolean
- {}
cdnRegions:
type: array
items:
type: object
properties:
provider:
enum:
- gcp
- aws
region:
enum:
- us
- eu
required:
- provider
- region
required:
- cdnRegions
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
private:
anyOf:
- type: boolean
- type: boolean
cdnRegions:
type: array
items:
type: object
properties:
provider:
enum:
- gcp
- aws
region:
enum:
- us
- eu
required:
- provider
- region
additionalProperties: false
additionalProperties: false
description: The updated bucket settings.
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/buckets/{namespace}:
get:
summary: List namespace buckets
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
description: Bucket overview information
type: object
properties:
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
author:
type: string
id:
type: string
private:
anyOf:
- type: boolean
- type: 'null'
createdAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
updatedAt:
type: string
format: date-time
pattern: ^((\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-((0[13578]|1[02])-(0[1-9]|[12]\d|3[01])|(0[469]|11)-(0[1-9]|[12]\d|30)|(02)-(0[1-9]|1\d|2[0-8])))T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z)$
size:
description: The amount of storage used by the bucket in bytes
type: number
totalFiles:
description: The total number of files in the bucket
type: number
repoType:
const: bucket
cdnRegions:
type: array
items:
type: object
properties:
provider:
enum:
- gcp
- aws
region:
enum:
- us
- eu
required:
- provider
- region
additionalProperties: false
resourceGroup:
type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
name:
type: string
numUsers:
type: number
required:
- id
- name
additionalProperties: false
required:
- _id
- author
- id
- createdAt
- updatedAt
- size
- totalFiles
- repoType
- cdnRegions
additionalProperties: false
description: List of buckets
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: search
in: query
schema:
type: string
required: false
/buckets/{namespace}/{repo}/resolve/{path}:
get:
description: Returns file metadata including size, hash, and links to XET authentication
summary: Retrieve information about a file in a bucket
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
hash:
description: The XET hash of the file
type: string
refreshUrl:
description: The XET auth URL for the file
type: string
reconstructionUrl:
description: The XET reconstruction URL for the file
type: string
etag:
description: The ETag of the file
type: string
size:
description: The size of the file
type: number
contentType:
description: The content type of the file
type: string
required:
- hash
- refreshUrl
- reconstructionUrl
- etag
- size
additionalProperties: false
description: XET file info returned when the Accept header is set to `application/vnd.xet-fileinfo+json`. Otherwise, a 302 redirect is returned.
'302':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Redirection to file on the xet bridge (default when no specific Accept header is set)
'400':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: string
required:
- error
additionalProperties: false
description: File path required
'404':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
error:
type: string
required:
- error
additionalProperties: false
description: Bucket or file not found
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: path
in: path
required: true
schema:
type: string
description: Wildcard path parameter
- name: noContentDisposition
in: query
schema: {}
required: false
- name: download
in: query
schema: {}
required: false
- name: Accept
in: header
schema:
$schema: https://json-schema.org/draft/2020-12/schema
description: Returns json information about the XET file info
const: application/vnd.xet-fileinfo+json
/api/buckets/{namespace}/{repo}/batch:
post:
description: "Accepts NDJSON (newline-delimited JSON) where each line is an addFile, copyFile, or deleteFile instruction.\nAll add/copy operations must come before all delete operations.\n\nJSON-lines payload:\n```json\n\t'{\"type\":\"addFile\",\"path\":\"...\",\"xetHash\":\"...\",\"mtime\":...,\"contentType\":\"...\"}' +\n\t'{\"type\":\"copyFile\",\"path\":\"...\",\"xetHash\":\"...\",\"sourceRepoType\":\"...\",\"sourceRepoId\":\"...\"}' +\n\t'{\"type\":\"deleteFile\",\"path\":\"...\"}'\n```"
summary: Batch file operations
tags:
- buckets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
success:
description: True if all operations succeeded
type: boolean
processed:
description: Total number of operations attempted
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
succeeded:
description: Number of successful operations
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
failed:
description: List of failed operations
type: array
items:
type: object
properties:
path:
description: File path that failed
type: string
error:
description: Error message
type: string
required:
- path
- error
additionalProperties: false
required:
- success
- processed
- succeeded
- failed
additionalProperties: false
description: Batch operation status
'422':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
success:
description: True if all operations succeeded
type: boolean
processed:
description: Total number of operations attempted
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
succeeded:
description: Number of successful operations
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
failed:
description: List of failed operations
type: array
items:
type: object
properties:
path:
description: File path that failed
type: string
error:
description: Error message
type: string
required:
- path
- error
additionalProperties: false
required:
- success
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hugging-face-transformers/refs/heads/main/openapi/hugging-face-transformers-buckets-api-openapi.yml