openapi: 3.1.0
info:
  title: Hub API Endpoints agentic-provisioning notifications 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: notifications
  x-displayName: Notifications
  description: The following endpoints fetch Hub notifications.
paths:
  /api/notifications:
    get:
      description: List notifications for the user
      summary: List notifications
      tags:
      - notifications
      responses:
        '200':
          content:
            application/json:
              schema:
                $schema: https://json-schema.org/draft/2020-12/schema
                type: object
                properties:
                  notifications:
                    type: array
                    items:
                      anyOf:
                      - type: object
                        properties:
                          type:
                            const: paper
                          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)$
                          read:
                            type: boolean
                          discussionEventId:
                            type: string
                          paper:
                            type: object
                            properties:
                              _id:
                                type: string
                                minLength: 24
                                maxLength: 24
                                pattern: ^[0-9a-f]{24}$
                              title:
                                type: string
                            required:
                            - _id
                            - title
                            additionalProperties: false
                          paperDiscussion:
                            type: object
                            properties:
                              id:
                                type: string
                              participating:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    _id:
                                      type: string
                                      minLength: 24
                                      maxLength: 24
                                      pattern: ^[0-9a-f]{24}$
                                    avatar:
                                      type: string
                                    user:
                                      type: string
                                  required:
                                  - _id
                                  - avatar
                                  - user
                                  additionalProperties: false
                              paperId:
                                type: string
                                minLength: 24
                                maxLength: 24
                                pattern: ^[0-9a-f]{24}$
                            required:
                            - id
                            - participating
                            - paperId
                            additionalProperties: false
                        required:
                        - type
                        - updatedAt
                        - read
                        - paper
                        - paperDiscussion
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            const: repo
                          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)$
                          read:
                            type: boolean
                          discussionEventId:
                            type: string
                          repo:
                            $ref: '#/components/schemas/RepoId'
                          discussion:
                            type: object
                            properties:
                              num:
                                type: number
                              title:
                                type: string
                              status:
                                enum:
                                - draft
                                - open
                                - closed
                                - merged
                              id:
                                type: string
                                minLength: 24
                                maxLength: 24
                                pattern: ^[0-9a-f]{24}$
                              isPullRequest:
                                type: boolean
                              participating:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    _id:
                                      type: string
                                      minLength: 24
                                      maxLength: 24
                                      pattern: ^[0-9a-f]{24}$
                                    avatar:
                                      type: string
                                    user:
                                      type: string
                                  required:
                                  - _id
                                  - avatar
                                  - user
                                  additionalProperties: false
                            required:
                            - num
                            - title
                            - status
                            - id
                            - isPullRequest
                            - participating
                            additionalProperties: false
                        required:
                        - type
                        - updatedAt
                        - read
                        - repo
                        - discussion
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            const: post
                          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)$
                          read:
                            type: boolean
                          discussionEventId:
                            type: string
                          post:
                            type: object
                            properties:
                              id:
                                type: string
                              slug:
                                type: string
                              authorName:
                                type: string
                              title:
                                type: string
                              participating:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    _id:
                                      type: string
                                      minLength: 24
                                      maxLength: 24
                                      pattern: ^[0-9a-f]{24}$
                                    avatar:
                                      type: string
                                    user:
                                      type: string
                                  required:
                                  - _id
                                  - avatar
                                  - user
                                  additionalProperties: false
                            required:
                            - id
                            - slug
                            - authorName
                            - title
                            - participating
                            additionalProperties: false
                        required:
                        - type
                        - updatedAt
                        - read
                        - post
                        additionalProperties: false
                      - type: object
                        properties:
                          type:
                            const: community_blog
                          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)$
                          read:
                            type: boolean
                          discussionEventId:
                            type: string
                          blog:
                            type: object
                            properties:
                              id:
                                type: string
                              slug:
                                type: string
                              title:
                                type: string
                              canonical:
                                type: boolean
                              authorName:
                                type: string
                              participating:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    _id:
                                      type: string
                                      minLength: 24
                                      maxLength: 24
                                      pattern: ^[0-9a-f]{24}$
                                    avatar:
                                      type: string
                                    user:
                                      type: string
                                  required:
                                  - _id
                                  - avatar
                                  - user
                                  additionalProperties: false
                            required:
                            - id
                            - slug
                            - title
                            - canonical
                            - participating
                            additionalProperties: false
                        required:
                        - type
                        - updatedAt
                        - read
                        - blog
                        additionalProperties: false
                  count:
                    type: object
                    properties:
                      view:
                        type: number
                      unread:
                        type: number
                      all:
                        type: number
                    required:
                    - view
                    - unread
                    - all
                    additionalProperties: false
                  start:
                    type: number
                required:
                - notifications
                - count
                - start
                additionalProperties: false
          description: The notifications for the user
      parameters:
      - name: p
        in: query
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        required: false
      - name: readStatus
        in: query
        schema:
          default: all
          enum:
          - all
          - unread
        required: false
      - name: repoType
        in: query
        schema:
          enum:
          - dataset
          - model
          - space
          - bucket
          - kernel
        required: false
      - name: repoName
        in: query
        schema:
          type: string
        required: false
      - name: postAuthor
        in: query
        schema:
          type: string
        required: false
      - name: paperId
        in: query
        schema:
          type: string
        required: false
      - name: articleId
        in: query
        schema:
          type: string
        required: false
      - name: mention
        in: query
        schema:
          default: all
          enum:
          - all
          - participating
          - mentions
        required: false
      - name: lastUpdate
        in: query
        schema:
          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: false
    delete:
      description: Delete notifications, either by specifying discussionIds or by applying to all notifications with search parameters
      summary: Delete notifications
      tags:
      - notifications
      requestBody:
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                discussionIds:
                  minItems: 1
                  type: array
                  items:
                    type: string
                    minLength: 24
                    maxLength: 24
                    pattern: ^[0-9a-f]{24}$
      parameters:
      - name: p
        in: query
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        required: false
      - name: readStatus
        in: query
        schema:
          default: all
          enum:
          - all
          - unread
        required: false
      - name: repoType
        in: query
        schema:
          enum:
          - dataset
          - model
          - space
          - bucket
          - kernel
        required: false
      - name: repoName
        in: query
        schema:
          type: string
        required: false
      - name: postAuthor
        in: query
        schema:
          type: string
        required: false
      - name: paperId
        in: query
        schema:
          type: string
        required: false
      - name: articleId
        in: query
        schema:
          type: string
        required: false
      - name: mention
        in: query
        schema:
          default: all
          enum:
          - all
          - participating
          - mentions
        required: false
      - name: lastUpdate
        in: query
        schema:
          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: false
      - name: applyToAll
        in: query
        schema:
          default: false
        required: false
  /api/notifications/mark-as-read:
    post:
      description: Mark discussions as read or unread. If `applyToAll` is true, all notifications for the user matching the search parameters will be marked as read or unread.
      summary: Change read status
      tags:
      - notifications
      requestBody:
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                discussionIds:
                  default: []
                  type: array
                  items:
                    type: string
                read:
                  default: true
                  type: boolean
      parameters:
      - name: p
        in: query
        schema:
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        required: false
      - name: readStatus
        in: query
        schema:
          default: all
          enum:
          - all
          - unread
        required: false
      - name: repoType
        in: query
        schema:
          enum:
          - dataset
          - model
          - space
          - bucket
          - kernel
        required: false
      - name: repoName
        in: query
        schema:
          type: string
        required: false
      - name: postAuthor
        in: query
        schema:
          type: string
        required: false
      - name: paperId
        in: query
        schema:
          type: string
        required: false
      - name: articleId
        in: query
        schema:
          type: string
        required: false
      - name: mention
        in: query
        schema:
          default: all
          enum:
          - all
          - participating
          - mentions
        required: false
      - name: lastUpdate
        in: query
        schema:
          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: false
      - name: applyToAll
        in: query
        schema:
          default: false
        required: false
  /api/settings/notifications:
    patch:
      description: Update notification settings for the user
      summary: Update notification settings
      tags:
      - notifications
      requestBody:
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                notifications:
                  type: object
                  properties:
                    announcements:
                      type: boolean
                    arxiv_paper_activity:
                      type: boolean
                    daily_papers_digest:
                      type: boolean
                    discussions_participating:
                      type: boolean
                    discussions_watched:
                      type: boolean
                    gated_user_access_request:
                      type: boolean
                    inference_endpoint_status:
                      type: boolean
                    launch_autonlp:
                      type: boolean
                    launch_spaces:
                      type: boolean
                    launch_prepaid_credits:
                      type: boolean
                    launch_training_cluster:
                      type: boolean
                    org_request:
                      type: boolean
                    org_suggestions:
                      type: boolean
                    org_verified_suggestions:
                      type: boolean
                    org_suggestions_to_create:
                      type: boolean
                    posts_participating:
                      type: boolean
                    user_follows:
                      type: boolean
                    secret_detected:
                      type: boolean
                    web_discussions_participating:
                      type: boolean
                    web_discussions_watched:
                      type: boolean
                    web_posts_participating:
                      type: boolean
                    product_updates_after:
                      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)$
                    api_inference_sunset:
                      type: boolean
                    locked_out:
                      type: boolean
                prepaidAmount:
                  description: To be provided when enabling launch_prepaid_credits
                  type: string
                  maxLength: 24
              required:
              - notifications
  /api/settings/watch:
    patch:
      description: Update watch settings for the user. Get notified when discussions happen on your watched items.
      summary: Update watch settings
      tags:
      - notifications
      requestBody:
        content:
          application/json:
            schema:
              $schema: https://json-schema.org/draft/2020-12/schema
              type: object
              properties:
                delete:
                  default: []
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        enum:
                        - org
                        - user
                        - repo
                    required:
                    - id
                    - type
                add:
                  default: []
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                      type:
                        enum:
                        - org
                        - user
                        - repo
                    required:
                    - id
                    - type
components:
  schemas:
    RepoId:
      $schema: https://json-schema.org/draft/2020-12/schema
      type: object
      properties:
        name:
          examples:
          - deepseek-ai/DeepSeek-R1
          - black-forest-labs/FLUX.1-dev
          type: string
        type:
          enum:
          - dataset
          - model
          - space
          - bucket
          - kernel
      required:
      - name
      - type
      additionalProperties: false
      id: RepoId
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer