The following endpoints let you interact with Hub Organizations and their members.
openapi: 3.1.0
info:
title: Hub API Endpoints agentic-provisioning orgs 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: orgs
x-displayName: Organizations
description: The following endpoints let you interact with Hub Organizations and their members.
paths:
/api/organizations/{name}/settings/tokens/revoke:
post:
description: An org admin can revoke a token's access to the org. The token itself isn't deleted, it still works outside the org. Requires the raw token value. Enterprise only.
summary: Revoke a member's access token from the organization
tags:
- orgs
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
token:
type: string
pattern: ^hf_.*
required:
- token
parameters:
- name: name
in: path
required: true
schema:
type: string
/api/organizations/{name}/settings/repositories:
get:
summary: List organization repositories with storage info
tags:
- orgs
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: Organization repositories with storage usage
parameters:
- name: name
in: path
required: true
schema:
type: string
- 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/organizations/{name}/audit-log/export:
get:
description: Export the audit log events in JSON format for a Team or Enterprise organization. The export is limited to the last 100,000 events.
summary: Export the audit log
tags:
- orgs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
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)$
type:
enum:
- billing.update_payment_method
- billing.create_customer
- billing.remove_payment_method
- billing.aws_add
- billing.aws_remove
- billing.gcp_add
- billing.gcp_remove
- billing.marketplace_approve
- billing.cancel_subscription
- billing.renew_subscription
- billing.start_subscription
- billing.un_cancel_subscription
- billing.update_subscription
- billing.update_subscription_plan
- collection.create
- collection.delete
- org.add_user
- org.change_role
- org.create
- org.delete
- org.restore
- org.invite_user
- org.invite.accept
- org.invite.email
- org.join.from_domain
- org.join.automatic
- org.leave
- org.remove_user
- org.rename
- org.rotate_token
- org.sso_login
- org.sso_join
- org.update_join_settings
- org.update_settings
- org.token_approval.enabled
- org.token_approval.disabled
- org.token_approval.authorization_request
- org.token_approval.authorization_request.authorized
- org.token_approval.authorization_request.revoked
- org.token_approval.authorization_request.denied
- org.custom_role.create
- org.custom_role.update
- org.custom_role.delete
- repo.add_secrets
- repo.remove_secrets
- repo.add_secret
- repo.update_secret
- repo.remove_secret
- repo.create
- repo.delete
- repo.disable
- repo.removeDisable
- repo.duplication
- repo.delete_doi
- repo.move
- repo.update_resource_group
- repo.update_settings
- repo.add_variable
- repo.update_variable
- repo.remove_variable
- repo.add_variables
- repo.remove_variables
- repo.delete_lfs_file
- spaces.add_storage
- spaces.remove_storage
- spaces.set_volumes
- spaces.remove_volumes
- spaces.update_hardware
- spaces.update_sleep_time
- resource_group.create
- resource_group.add_users
- resource_group.remove_users
- resource_group.change_role
- resource_group.settings
- resource_group.delete
- jobs.create
- jobs.cancel
- jobs.update_labels
- scheduled_job.create
- scheduled_job.delete
- scheduled_job.resume
- scheduled_job.suspend
- scheduled_job.run
- scheduled_job.update_schedule
- scheduled_job.update_labels
- oauth.token
data: {}
message:
type: string
ip:
type: string
location:
type: object
properties:
formatted:
type: string
country:
type: string
city:
type: string
required:
- formatted
additionalProperties: false
userAgent:
type: string
author:
type: object
properties:
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
user:
type: string
avatarUrl:
type: string
type:
enum:
- user
- system
deleted:
type: boolean
required:
- _id
- user
- avatarUrl
- type
additionalProperties: false
token:
type: object
properties:
type:
const: access_token
id:
type: string
role:
enum:
- read
- write
- fineGrained
last4:
type: string
deleted:
type: boolean
required:
- type
- id
- deleted
additionalProperties: false
oauth:
type: object
properties:
clientId:
type: string
name:
type: string
required:
- clientId
additionalProperties: false
required:
- _id
- createdAt
- type
- message
- author
additionalProperties: false
description: Array of audit log events
headers:
Content-Disposition:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: string
description: The filename of the exported audit log
parameters:
- name: name
in: path
required: true
schema:
type: string
- name: q
in: query
schema:
examples:
- author:huggingface
- ip:127.0.0.0
- type:repo.create
type: string
required: false
/api/organizations/{name}/settings/network-security:
get:
description: Get the network security settings for an organization.
summary: Get network security settings
tags:
- orgs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
enforceAuth:
anyOf:
- type: boolean
- const: pending
enforceIpRestriction:
type: boolean
highRateLimits:
anyOf:
- type: boolean
- const: pending
ipRanges:
type: array
items:
type: string
blockedContents:
type: array
items:
type: object
properties:
resource:
anyOf:
- enum:
- dataset
- model
- space
- bucket
- kernel
- const: '*'
scope:
type: string
minLength: 1
required:
- resource
- scope
additionalProperties: false
allowedContents:
type: array
items:
type: object
properties:
resource:
anyOf:
- enum:
- dataset
- model
- space
- bucket
- kernel
- const: '*'
scope:
type: string
minLength: 1
required:
- resource
- scope
additionalProperties: false
required:
- enforceAuth
- enforceIpRestriction
- highRateLimits
- ipRanges
- blockedContents
- allowedContents
additionalProperties: false
description: Network security settings
parameters:
- name: name
in: path
required: true
schema:
type: string
patch:
description: Update the network security settings for an organization.
summary: Update network security settings
tags:
- orgs
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
enforceAuth:
type: boolean
enforceIpRestriction:
type: boolean
highRateLimits:
type: boolean
ipRanges:
minItems: 1
type: array
items:
anyOf:
- type: string
format: cidrv4
pattern: ^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$
- type: string
format: cidrv6
pattern: ^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::|([0-9a-fA-F]{1,4})?::([0-9a-fA-F]{1,4}:?){0,6})\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$
blockedContents:
type: array
items:
type: object
properties:
resource:
anyOf:
- enum:
- dataset
- model
- space
- bucket
- kernel
- const: '*'
scope:
type: string
minLength: 1
required:
- resource
- scope
allowedContents:
type: array
items:
type: object
properties:
resource:
anyOf:
- enum:
- dataset
- model
- space
- bucket
- kernel
- const: '*'
scope:
type: string
minLength: 1
required:
- resource
- scope
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
enforceAuth:
anyOf:
- type: boolean
- const: pending
enforceIpRestriction:
type: boolean
highRateLimits:
anyOf:
- type: boolean
- const: pending
ipRanges:
type: array
items:
type: string
blockedContents:
type: array
items:
type: object
properties:
resource:
anyOf:
- enum:
- dataset
- model
- space
- bucket
- kernel
- const: '*'
scope:
type: string
minLength: 1
required:
- resource
- scope
additionalProperties: false
allowedContents:
type: array
items:
type: object
properties:
resource:
anyOf:
- enum:
- dataset
- model
- space
- bucket
- kernel
- const: '*'
scope:
type: string
minLength: 1
required:
- resource
- scope
additionalProperties: false
required:
- enforceAuth
- enforceIpRestriction
- highRateLimits
- ipRanges
- blockedContents
- allowedContents
additionalProperties: false
description: Updated network security settings
parameters:
- name: name
in: path
required: true
schema:
type: string
/api/organizations/{name}/avatar:
get:
description: 'Retrieve organization avatar. This endpoint returns a JSON with the avatar URL for the organization.
If called with the `Sec-Fetch-Dest: image` header, it instead redirects to the avatar URL'
summary: Get avatar
tags:
- orgs
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: name
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/organizations/{name}/members:
get:
description: Get a list of members for the organization with optional search and pagination.
summary: Get organization members
tags:
- orgs
responses:
'200':
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: array
items:
type: object
properties:
avatarUrl:
type: string
fullname:
type: string
isPro:
type: boolean
user:
type: string
type:
const: user
isFollowing:
type: boolean
_id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-f]{24}$
role:
anyOf:
- enum:
- admin
- write
- contributor
- read
- no_access
- description: Custom role name
type: string
resourceGroups:
type: array
items:
type: object
properties:
name:
type: string
id:
type: string
numUsers:
type: number
role:
anyOf:
- enum:
- admin
- write
- contributor
- read
- no_access
- description: Custom role name
type: string
required:
- name
- id
- numUsers
- role
additionalProperties: false
twoFaEnabled:
type: boolean
verifiedEmail:
description: The user's SSO email, if the org has a Team or Enterprise plan and the requester is an admin
anyOf:
- type: string
- type: 'null'
isExternalCollaborator:
type: boolean
required:
- avatarUrl
- fullname
- isPro
- user
- type
- _id
additionalProperties: false
description: Array of organization members
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: name
in: path
required: true
schema:
type: string
- name: search
in: query
schema:
type: string
required: false
- name: email
in: query
schema:
type: string
format: email
pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
required: false
- name: cursor
in: query
schema:
type: string
required: false
- name: limit
in: query
schema:
default: 500
type: integer
minimum: 10
maximum: 10000
required: false
/api/organizations/{name}/members/{username}/role:
put:
description: Change the role of a member in the organization. Need a paid plan.
summary: Change member role
tags:
- orgs
requestBody:
content:
application/json:
schema:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
role:
anyOf:
- enum:
- admin
- write
- contributor
- read
- no_access
- description: Custom role name
type: string
resourceGroups:
type: array
items:
type: object
properties:
id:
type: string
minLength: 24
maxLength: 24
pattern: ^[0-9a-fA-F]{24}$
role:
anyOf:
- enum:
- admin
- write
- contributor
- read
- no_access
- description: Custom role name
type: string
required:
- id
- role
required:
- role
parameters:
- name: name
in: path
required: true
schema:
type: string
- name: username
in: path
required: true
schema:
type: string
/api/organizations/{name}/billing/usage:
get:
description: Get org usage for a given period
summary: Get org usage
tags:
- orgs
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
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hugging-face-transformers/refs/heads/main/openapi/hugging-face-transformers-orgs-api-openapi.yml