User accounts are the base authoring entity on the Hub
openapi: 3.1.0
info:
title: Hub API Endpoints agentic-provisioning users 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: users
x-displayName: Users
description: User accounts are the base authoring entity on the Hub
paths:
/api/settings/mcp:
get:
description: Get the MCP tools for the current user
summary: Get MCP tools
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
builtInTools:
type: array
items:
type: string
spaceTools:
type: array
items:
type: object
properties:
_id:
type: string
name:
type: string
emoji:
type: string
subdomain:
type: string
required:
- _id
- name
- emoji
- subdomain
additionalProperties: false
required:
- builtInTools
- spaceTools
additionalProperties: false
description: The MCP tools for the current user
/api/settings/repositories:
get:
summary: List user repositories with storage info
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
id:
type: string
type:
enum:
- dataset
- model
- space
- bucket
- kernel
updatedAt:
type: string
visibility:
enum:
- public
- private
- protected
storage:
type: number
storagePercent:
type: number
required:
- id
- type
- updatedAt
- visibility
- storage
- storagePercent
additionalProperties: false
description: Repositories with storage usage
parameters:
- name: search
in: query
schema:
description: Filter repositories by name (case-insensitive substring match)
type: string
required: false
- name: type
in: query
schema:
description: Filter by repository type
enum:
- dataset
- model
- space
- bucket
- kernel
required: false
- name: limit
in: query
schema:
description: Max number of repositories to return
type: integer
minimum: 1
maximum: 9007199254740991
required: false
- name: sort
in: query
schema:
description: 'Sort field (default: storage)'
default: storage
enum:
- storage
- updatedAt
required: false
- name: direction
in: query
schema:
description: 'Sort direction (default: desc)'
default: desc
enum:
- asc
- desc
required: false
/api/settings/billing/usage:
get:
description: Get user usage for a given period
summary: Get user usage
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
usage:
type: object
propertyNames:
anyOf:
- enum:
- Endpoints
- Spaces
- not: {}
additionalProperties:
type: array
items:
type: object
properties:
entityId:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
label:
anyOf:
- type: string
- type: 'null'
product:
enum:
- hf/repository-storage
- jobs/cpu-basic/minutes
- jobs/cpu-upgrade/minutes
- jobs/cpu-performance/minutes
- jobs/cpu-xl/minutes
- jobs/sprx8/minutes
- jobs/t4-small/minutes
- jobs/t4-medium/minutes
- jobs/a10g-small/minutes
- jobs/a10g-large/minutes
- jobs/a10g-largex2/minutes
- jobs/a10g-largex4/minutes
- jobs/a100-large/minutes
- jobs/a100x4/minutes
- jobs/a100x8/minutes
- jobs/h100/minutes
- jobs/h100x8/minutes
- jobs/h200/minutes
- jobs/h200x2/minutes
- jobs/h200x4/minutes
- jobs/h200x8/minutes
- jobs/rtx-pro-6000/minutes
- jobs/rtx-pro-6000x2/minutes
- jobs/rtx-pro-6000x4/minutes
- jobs/rtx-pro-6000x8/minutes
- jobs/l4x1/minutes
- jobs/l4x4/minutes
- jobs/l40sx1/minutes
- jobs/l40sx4/minutes
- jobs/l40sx8/minutes
- jobs/v5e-2x4/minutes
- jobs/v5e-2x2/minutes
- jobs/v5e-1x1/minutes
- jobs/inf2x6/minutes
- spaces/zero-a10g/minutes
- spaces/cpu-basic/minutes
- spaces/cpu-upgrade/minutes
- spaces/cpu-performance/minutes
- spaces/cpu-xl/minutes
- spaces/sprx8/minutes
- spaces/t4-small/minutes
- spaces/t4-medium/minutes
- spaces/a10g-small/minutes
- spaces/a10g-large/minutes
- spaces/a10g-largex2/minutes
- spaces/a10g-largex4/minutes
- spaces/a100-large/minutes
- spaces/a100x4/minutes
- spaces/a100x8/minutes
- spaces/h100/minutes
- spaces/h100x8/minutes
- spaces/h200/minutes
- spaces/h200x2/minutes
- spaces/h200x4/minutes
- spaces/h200x8/minutes
- spaces/rtx-pro-6000/minutes
- spaces/rtx-pro-6000x2/minutes
- spaces/rtx-pro-6000x4/minutes
- spaces/rtx-pro-6000x8/minutes
- spaces/l4x1/minutes
- spaces/l4x4/minutes
- spaces/l40sx1/minutes
- spaces/l40sx4/minutes
- spaces/l40sx8/minutes
- spaces/inf2x6/minutes
- spaces/v5e-2x4/minutes
- spaces/v5e-2x2/minutes
- spaces/v5e-1x1/minutes
- spaces/storage-small/minutes
- spaces/storage-medium/minutes
- spaces/storage-large/minutes
- endpoints/azure/intel-xeon/x1
- endpoints/azure/intel-xeon/x2
- endpoints/azure/intel-xeon/x4
- endpoints/azure/intel-xeon/x8
- endpoints/aws/intel-icl/x1
- endpoints/aws/intel-icl/x2
- endpoints/aws/intel-icl/x4
- endpoints/aws/intel-icl/x8
- endpoints/aws/intel-spr/x1
- endpoints/aws/intel-spr/x2
- endpoints/aws/intel-spr/x4
- endpoints/aws/intel-spr/x8
- endpoints/aws/intel-spr/x16
- endpoints/aws/intel-spr-overcommitted/x16
- endpoints/aws/nvidia-t4/x1
- endpoints/aws/nvidia-t4/x4
- endpoints/aws/nvidia-l4/x1
- endpoints/aws/nvidia-l4/x4
- endpoints/aws/nvidia-l40s/x1
- endpoints/aws/nvidia-l40s/x4
- endpoints/aws/nvidia-l40s/x8
- endpoints/aws/nvidia-a10g/x1
- endpoints/aws/nvidia-a10g/x4
- endpoints/aws/nvidia-a100/x1
- endpoints/aws/nvidia-a100/x2
- endpoints/aws/nvidia-a100/x4
- endpoints/aws/nvidia-a100/x8
- endpoints/aws/nvidia-h100/x1
- endpoints/aws/nvidia-h100/x2
- endpoints/aws/nvidia-h100/x4
- endpoints/aws/nvidia-h100/x8
- endpoints/aws/nvidia-h200/x1
- endpoints/aws/nvidia-h200/x2
- endpoints/aws/nvidia-h200/x4
- endpoints/aws/nvidia-h200/x8
- endpoints/aws/nvidia-b200/x1
- endpoints/aws/nvidia-b200/x2
- endpoints/aws/nvidia-b200/x4
- endpoints/aws/nvidia-b200/x8
- endpoints/aws/nvidia-rtx-pro-6000/x1
- endpoints/aws/nvidia-rtx-pro-6000/x2
- endpoints/aws/nvidia-rtx-pro-6000/x4
- endpoints/aws/nvidia-rtx-pro-6000/x8
- endpoints/aws/inf2/x1
- endpoints/aws/inf2/x1-large
- endpoints/aws/inf2/x12
- endpoints/gcp/intel-spr/x1
- endpoints/gcp/intel-spr/x2
- endpoints/gcp/intel-spr/x4
- endpoints/gcp/intel-spr/x8
- endpoints/gcp/nvidia-t4/x1
- endpoints/gcp/nvidia-l4/x1
- endpoints/gcp/nvidia-l4/x4
- endpoints/gcp/nvidia-a100/x1
- endpoints/gcp/nvidia-a100/x2
- endpoints/gcp/nvidia-a100/x4
- endpoints/gcp/nvidia-a100/x8
- endpoints/gcp/nvidia-h100/x1
- endpoints/gcp/nvidia-h100/x2
- endpoints/gcp/nvidia-h100/x4
- endpoints/gcp/nvidia-h100/x8
- endpoints/gcp/v5e/1x1
- endpoints/gcp/v5e/2x2
- endpoints/gcp/v5e/2x4
quantity:
type: number
startedAt:
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)$
stoppedAt:
anyOf:
- 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)$
- type: 'null'
freeGrant:
type: boolean
productPrettyName:
type: string
unitLabel:
anyOf:
- type: string
- type: 'null'
totalCostMicroUSD:
type: number
unitCostMicroUSD:
type: number
active:
type: boolean
required:
- entityId
- label
- product
- quantity
- productPrettyName
- unitLabel
- totalCostMicroUSD
- unitCostMicroUSD
- active
additionalProperties: false
period:
type: object
properties:
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
entityId:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
entityType:
enum:
- user
- org
entityName:
type: string
periodStart:
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)$
periodEnd:
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)$
invoice:
anyOf:
- type: object
properties:
type:
const: stripe
id:
type: string
amountDueCents:
type: number
totalCents:
type: number
status:
enum:
- draft
- open
- paid
- uncollectible
- void
- unpaid
dueDate:
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)$
collectionMethod:
enum:
- charge_automatically
- send_invoice
required:
- type
- id
- amountDueCents
- totalCents
- status
- dueDate
additionalProperties: false
- type: object
properties:
type:
const: no-invoice
id:
const: no-invoice
required:
- type
- id
additionalProperties: false
charges:
type: array
items:
type: object
properties:
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
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)$
dueDate:
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)$
usageAtChargeTimeMicroUSD:
type: number
amountCents:
type: number
billedThrough:
enum:
- stripe-payment-intent
paymentIntentId:
type: string
paymentIntentStatus:
enum:
- canceled
- processing
- requires_action
- requires_capture
- requires_confirmation
- requires_payment_method
- succeeded
required:
- _id
- createdAt
- dueDate
- usageAtChargeTimeMicroUSD
- amountCents
- billedThrough
- paymentIntentId
- paymentIntentStatus
additionalProperties: false
required:
- _id
- entityId
- entityType
- entityName
- periodStart
- periodEnd
additionalProperties: false
required:
- usage
- period
additionalProperties: false
description: Usage and period information
parameters:
- name: periodId
in: query
schema:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
required: false
/api/settings/billing/usage-v2:
get:
description: Get user usage for a given period
summary: Get user usage
tags:
- users
parameters:
- name: startDate
in: query
schema:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
required: true
- name: endDate
in: query
schema:
type: integer
exclusiveMinimum: 0
maximum: 9007199254740991
required: true
/api/settings/billing/usage/jobs:
get:
description: Get user Jobs usage for current subscription period
summary: Get jobs usage
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
usage:
type: object
properties:
usedMicroUsd:
type: number
totalMinutes:
type: number
periodStart:
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)$
periodEnd:
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)$
jobDetails:
type: array
items:
type: object
properties:
jobId:
type: string
hardwareFlavor:
type: string
totalMinutes:
type: number
totalCostMicroUsd:
type: number
startedAt:
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)$
completedAt:
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)$
required:
- jobId
- hardwareFlavor
- totalMinutes
- totalCostMicroUsd
- startedAt
additionalProperties: false
required:
- usedMicroUsd
- totalMinutes
- periodStart
- periodEnd
- jobDetails
additionalProperties: false
hasAccess:
type: boolean
required:
- usage
- hasAccess
additionalProperties: false
description: Jobs usage information
/api/settings/billing/usage/live:
get:
description: Get live usage for user
summary: Stream usage
tags:
- users
/api/users/{username}/billing/usage/live:
get:
description: Get live usage for user
summary: Stream usage
tags:
- users
parameters:
- name: username
in: path
required: true
schema:
type: string
/api/users/{username}/overview:
get:
summary: User overview
tags:
- users
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}$
orgs:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
fullname:
type: string
avatarUrl:
type: string
required:
- id
- name
- fullname
- avatarUrl
additionalProperties: false
avatarUrl:
type: string
fullname:
type: string
isPro:
type: boolean
user:
type: string
numModels:
type: number
numDatasets:
type: number
numSpaces:
type: number
numDiscussions:
type: number
numPapers:
type: number
numUpvotes:
type: number
numLikes:
type: number
numFollowers:
type: number
numFollowing:
type: number
details:
type: string
isFollowing:
type: boolean
reasonToFollow:
type: string
type:
const: user
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)$
required:
- _id
- avatarUrl
- fullname
- isPro
- user
- type
- createdAt
additionalProperties: false
description: User overview data including their organizations, stats, and creation date
parameters:
- name: username
in: path
required: true
schema:
type: string
/api/users/{username}/socials:
get:
description: Get a user's social media handles
summary: Get social handles
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
_id:
type: string
user:
type: string
socialHandles:
type: object
properties:
twitter:
type: string
github:
type: string
linkedin:
type: string
bluesky:
type: string
additionalProperties: false
required:
- _id
- user
- socialHandles
additionalProperties: false
description: The user's social media handles. Only includes handles that the user has provided.
parameters:
- name: username
in: path
required: true
schema:
type: string
/api/users/{username}/avatar:
get:
description: 'This endpoint returns a JSON with the avatar URL for the user.
If called with the `Sec-Fetch-Dest: image` header, it instead redirects to the avatar URL'
summary: Retrieve user avatar
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
avatarUrl:
type: string
format: uri
required:
- avatarUrl
additionalProperties: false
description: Avatar URL
parameters:
- name: username
in: path
required: true
schema:
type: string
- name: redirect
in: query
schema:
description: Redirect to the avatar url instead of returning it
required: false
/api/users/{username}/likes:
get:
description: List public repos liked by a user
summary: List user likes
tags:
- users
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
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)$
repo:
ty
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hugging-face-transformers/refs/heads/main/openapi/hugging-face-transformers-users-api-openapi.yml