Get information from all datasets on the Hub.
openapi: 3.1.0
info:
title: Hub API Endpoints agentic-provisioning datasets 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: datasets
x-displayName: Datasets
description: Get information from all datasets on the Hub.
paths:
/api/datasets/{namespace}/{repo}/treesize/{rev}/{path}:
get:
description: Get the total size of a repository at a given revision, optionally under a specific subpath. Returns the total size in bytes of all files under the specified path (recursively). If a file is stored via Xet/LFS, the LFS file size is used.
summary: Get folder size
tags:
- datasets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
path:
description: The normalized path of the subtree, starting with a slash
type: string
size:
description: Total size in bytes of all files under the subtree
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- path
- size
additionalProperties: false
description: Total size of a repository at a given revision, under the given path
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: rev
in: path
required: true
schema:
type: string
- name: path
in: path
required: true
schema:
type: string
description: Wildcard path parameter
/api/datasets/{namespace}/{repo}/lfs-files:
get:
description: List Xet/LFS files for a repo
summary: List Large files
tags:
- datasets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
pusher:
type: object
properties:
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
avatarUrl:
type: string
fullname:
type: string
name:
type: string
isHf:
type: boolean
isHfAdmin:
type: boolean
isMod:
type: boolean
followerCount:
type: number
type:
const: user
isPro:
type: boolean
isUserFollowing:
type: boolean
primaryOrg:
type: object
properties:
avatarUrl:
type: string
fullname:
type: string
name:
type: string
type:
const: org
isHf:
type: boolean
isFollowing:
type: boolean
plan:
enum:
- team
- enterprise
- plus
- academia
details:
type: string
hasPrivateMembersList:
type: boolean
userRole:
anyOf:
- enum:
- admin
- write
- contributor
- read
- no_access
- description: Custom role name
type: string
numUsers:
type: number
required:
- avatarUrl
- fullname
- name
- type
- isHf
additionalProperties: false
required:
- _id
- avatarUrl
- fullname
- name
- isHf
- isHfAdmin
- isMod
- type
- isPro
additionalProperties: false
ref:
type: string
fileOid:
type: string
oid:
type: string
size:
type: number
pushedAt:
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)$
filename:
description: Potential filename of the LFS file
type: string
xetHash:
type: string
required:
- fileOid
- oid
- size
- pushedAt
additionalProperties: false
description: List of Xet/LFS files for the repo
headers:
Link:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
description: Link header for pagination, can contain a `rel="next"` link
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: cursor
in: query
schema:
type: string
required: false
- name: limit
in: query
schema:
default: 1000
type: integer
minimum: 1
maximum: 1000
required: false
- name: xet
in: query
schema: {}
required: false
/api/datasets/{namespace}/{repo}/lfs-files/batch:
post:
description: Delete Xet/LFS files in batch
summary: Delete Large files
tags:
- datasets
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
deletions:
type: object
properties:
sha:
minItems: 1
maxItems: 1000
type: array
items:
type: string
rewriteHistory:
default: true
type: boolean
required:
- sha
required:
- deletions
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
/api/datasets/{namespace}/{repo}/lfs-files/{sha}:
delete:
description: Delete a Xet/LFS file
summary: Delete Large file
tags:
- datasets
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: sha
in: path
required: true
schema:
type: string
- name: rewriteHistory
in: query
schema:
default: true
required: false
/api/datasets/{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:
- datasets
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/datasets/{namespace}/{repo}/commits/{rev}:
get:
summary: List commits
tags:
- datasets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
id:
type: string
title:
type: string
message:
type: string
authors:
type: array
items:
type: object
properties:
user:
type: string
avatar:
type: string
required:
- user
additionalProperties: false
date:
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)$
formatted:
description: Available if expand includes formatted
type: object
properties:
title:
type: string
message:
type: string
required:
- title
additionalProperties: false
required:
- id
- title
- message
- authors
- date
additionalProperties: false
description: Commits list
headers:
X-Total-Count:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
Link:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
description: Link to the next page
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: rev
in: path
required: true
schema:
type: string
- name: p
in: query
schema:
default: 0
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required: false
- name: expand
in: query
schema:
type: array
items:
enum:
- formatted
required: false
- name: limit
in: query
schema:
default: 50
type: integer
minimum: 1
maximum: 1000
required: false
/api/datasets/{namespace}/{repo}/refs:
get:
summary: List references
tags:
- datasets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
tags:
type: array
items:
type: object
properties:
name:
type: string
ref:
type: string
targetCommit:
type: string
required:
- name
- ref
- targetCommit
additionalProperties: false
branches:
type: array
items:
type: object
properties:
name:
type: string
ref:
type: string
targetCommit:
type: string
required:
- name
- ref
- targetCommit
additionalProperties: false
converts:
type: array
items:
type: object
properties:
name:
type: string
ref:
type: string
targetCommit:
type: string
required:
- name
- ref
- targetCommit
additionalProperties: false
pullRequests:
type: array
items:
type: object
properties:
name:
type: string
ref:
type: string
targetCommit:
type: string
required:
- name
- ref
- targetCommit
additionalProperties: false
required:
- tags
- branches
- converts
additionalProperties: false
description: List of references in the repository
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: include_prs
in: query
schema:
default: false
required: false
/api/datasets/{namespace}/{repo}/compare/{compare}:
get:
summary: Get a compare rev
tags:
- datasets
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
description: The diff between the two revisions
parameters:
- name: namespace
in: path
required: true
schema:
type: string
- name: repo
in: path
required: true
schema:
type: string
- name: compare
in: path
required: true
schema:
type: string
- name: raw
in: query
schema:
default: false
required: false
/api/datasets/{namespace}/{repo}/paths-info/{rev}:
post:
summary: List paths info
tags:
- datasets
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
paths:
anyOf:
- maxItems: 2000
type: array
items:
type: string
- type: string
expand:
description: Expand the response with the last commit and security file status
anyOf:
- default: false
- default: false
type: boolean
required:
- paths
- expand
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
type:
enum:
- file
- directory
- unknown
oid:
type: string
size:
type: number
lfs:
type: object
properties:
pointerSize:
type: number
required:
- pointerSize
additionalProperties: false
xetHash:
type: string
path:
type: string
lastCommit:
type: object
properties:
id:
type: string
title:
type: string
date:
type: string
required:
- id
- title
- date
additionalProperties: false
securityFileStatus:
type: object
properties:
status:
enum:
- unscanned
- safe
- queued
- error
- caution
- suspicious
- unsafe
jFrogScan:
type: object
properties:
status:
enum:
- unscanned
- safe
- queued
- error
- caution
- suspicious
- unsafe
message:
type: string
reportLink:
type: string
reportLabel:
type: string
pickleImports:
type: array
items:
type: object
properties:
module:
type: string
name:
type: string
safety:
enum:
- innocuous
- suspicious
- dangerous
required:
- module
- name
- safety
additionalProperties: false
version:
type: string
required:
- status
additionalProperties: false
protectAiScan:
type: object
properties:
status:
enum:
- unscanned
- safe
- queued
- error
- caution
- suspicious
- unsafe
message:
type: string
reportLink:
type: string
reportLabel:
type: string
pickleImports:
type: array
items:
type: object
properties:
module:
type: string
name:
type: string
safety:
enum:
- innocuous
- suspicious
- dangerous
required:
- module
- name
- safety
additionalProperties: false
version:
type: string
required:
- status
additionalProperties: false
avScan:
type: object
properties:
status:
enum:
- unscanned
- safe
- queued
- error
- caution
- suspicious
- unsafe
message:
type: string
reportLink:
type: string
reportLabel:
type: string
pickleImports:
type: array
items:
type: object
properties:
module:
type: string
name:
type: string
safety:
enum:
- innocuous
- suspicious
- dangerous
required:
- module
- name
- safety
additionalProperties: false
version:
type: string
required:
- status
additionalProperties: false
pickleImportScan:
type: object
properties:
status:
enum:
- unscanned
- safe
- queued
- error
- caution
- suspicious
- unsafe
message:
type: string
reportLink:
type: string
reportLabel:
type: string
pickleImports:
type: array
items:
type: object
properties:
module:
type: string
name:
type: string
safety:
enum:
- innocuous
- suspicious
- dangerous
required:
- module
- name
- safety
additionalProperties: false
version:
type: string
required:
- status
additional
# --- truncated at 32 KB (159 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hugging-face-transformers/refs/heads/main/openapi/hugging-face-transformers-datasets-api-openapi.yml