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: type: object properties: name: type: string type: enum: - dataset - model - space - bucket - kernel required: - name - type additionalProperties: false required: - createdAt - repo additionalProperties: false description: Likes on public repositories headers: Link: schema: $schema: https://json-schema.org/draft/2020-12/schema type: string description: Link to the next page parameters: - name: username in: path required: true schema: type: string - name: limit in: query schema: description: Max number of likes to return type: integer minimum: 1 maximum: 9007199254740991 required: false - name: cursor in: query schema: description: Cursor for pagination. Always check to see if more results, a page can be empty or not filled. type: string minLength: 24 maxLength: 24 pattern: ^[0-9a-f]{24}$ required: false /api/avatars/{namespace}: get: description: Display the avatar for any user or organization. This endpoint redirects to the avatar URL for either a user or an organization summary: Get avatar tags: - users parameters: - name: namespace in: path required: true schema: type: string components: securitySchemes: bearerAuth: type: http scheme: bearer