Gitea notification API

openapi: 3.2.0
info:
  description: This documentation describes the Gitea API.
  title: Gitea admin Notification API
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
  version: 1.27.0+dev-89-gf52b6f3315
servers:
- url: /api/v1
security:
- BasicAuth: []
- Token: []
- AccessToken: []
- AuthorizationHeaderToken: []
- SudoParam: []
- SudoHeader: []
- TOTPHeader: []
tags:
- name: notification
paths:
  /notifications:
    get:
      tags:
      - notification
      summary: List users's notification threads
      operationId: notifyGetList
      parameters:
      - description: If true, show notifications marked as read. Default value is false
        name: all
        in: query
        schema:
          type: boolean
      - description: 'Show notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread & pinned.'
        name: status-types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: filter notifications by subject type
        name: subject-type
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - issue
            - pull
            - commit
            - repository
            type: string
      - description: Only show notifications updated after the given time. This is a timestamp in RFC 3339 format
        name: since
        in: query
        schema:
          type: string
          format: date-time
      - description: Only show notifications updated before the given time. This is a timestamp in RFC 3339 format
        name: before
        in: query
        schema:
          type: string
          format: date-time
      - description: page number of results to return (1-based)
        name: page
        in: query
        schema:
          type: integer
      - description: page size of results
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/NotificationThreadList'
    put:
      tags:
      - notification
      summary: Mark notification threads as read, pinned or unread
      operationId: notifyReadList
      parameters:
      - description: Describes the last point that notifications were checked. Anything updated since this time will not be updated.
        name: last_read_at
        in: query
        schema:
          type: string
          format: date-time
      - description: If true, mark all notifications on this repo. Default value is false
        name: all
        in: query
        schema:
          type: string
      - description: 'Mark notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread.'
        name: status-types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: Status to mark notifications as, Defaults to read.
        name: to-status
        in: query
        schema:
          type: string
      responses:
        '205':
          $ref: '#/components/responses/NotificationThreadList'
  /notifications/new:
    get:
      tags:
      - notification
      summary: Check if unread notifications exist
      operationId: notifyNewAvailable
      responses:
        '200':
          $ref: '#/components/responses/NotificationCount'
  /notifications/threads/{id}:
    get:
      tags:
      - notification
      summary: Get notification thread by ID
      operationId: notifyGetThread
      parameters:
      - description: id of notification thread
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/NotificationThread'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    patch:
      tags:
      - notification
      summary: Mark notification thread as read by ID
      operationId: notifyReadThread
      parameters:
      - description: id of notification thread
        name: id
        in: path
        required: true
        schema:
          type: string
      - description: Status to mark notifications as
        name: to-status
        in: query
        schema:
          type: string
          default: read
      responses:
        '205':
          $ref: '#/components/responses/NotificationThread'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /repos/{owner}/{repo}/notifications:
    get:
      tags:
      - notification
      summary: List users's notification threads on a specific repo
      operationId: notifyGetRepoList
      parameters:
      - description: owner of the repo
        name: owner
        in: path
        required: true
        schema:
          type: string
      - description: name of the repo
        name: repo
        in: path
        required: true
        schema:
          type: string
      - description: If true, show notifications marked as read. Default value is false
        name: all
        in: query
        schema:
          type: boolean
      - description: 'Show notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread & pinned'
        name: status-types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: filter notifications by subject type
        name: subject-type
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            enum:
            - issue
            - pull
            - commit
            - repository
            type: string
      - description: Only show notifications updated after the given time. This is a timestamp in RFC 3339 format
        name: since
        in: query
        schema:
          type: string
          format: date-time
      - description: Only show notifications updated before the given time. This is a timestamp in RFC 3339 format
        name: before
        in: query
        schema:
          type: string
          format: date-time
      - description: page number of results to return (1-based)
        name: page
        in: query
        schema:
          type: integer
      - description: page size of results
        name: limit
        in: query
        schema:
          type: integer
      responses:
        '200':
          $ref: '#/components/responses/NotificationThreadList'
    put:
      tags:
      - notification
      summary: Mark notification threads as read, pinned or unread on a specific repo
      operationId: notifyReadRepoList
      parameters:
      - description: owner of the repo
        name: owner
        in: path
        required: true
        schema:
          type: string
      - description: name of the repo
        name: repo
        in: path
        required: true
        schema:
          type: string
      - description: If true, mark all notifications on this repo. Default value is false
        name: all
        in: query
        schema:
          type: string
      - description: 'Mark notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread.'
        name: status-types
        in: query
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - description: Status to mark notifications as. Defaults to read.
        name: to-status
        in: query
        schema:
          type: string
      - description: Describes the last point that notifications were checked. Anything updated since this time will not be updated.
        name: last_read_at
        in: query
        schema:
          type: string
          format: date-time
      responses:
        '205':
          $ref: '#/components/responses/NotificationThreadList'
components:
  responses:
    NotificationCount:
      description: Number of unread notifications
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationCount'
    notFound:
      description: APINotFound is a not found empty response
    forbidden:
      description: APIForbiddenError is a forbidden error response
      headers:
        message:
          schema:
            type: string
        url:
          schema:
            type: string
    NotificationThreadList:
      description: NotificationThreadList
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/NotificationThread'
    NotificationThread:
      description: NotificationThread
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotificationThread'
  schemas:
    RepoTransfer:
      description: RepoTransfer represents a pending repo transfer
      type: object
      properties:
        doer:
          $ref: '#/components/schemas/User'
        recipient:
          $ref: '#/components/schemas/User'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/Team'
          x-go-name: Teams
      x-go-package: code.gitea.io/gitea/modules/structs
    Permission:
      description: Permission represents a set of permissions
      type: object
      properties:
        admin:
          type: boolean
          x-go-name: Admin
        pull:
          type: boolean
          x-go-name: Pull
        push:
          type: boolean
          x-go-name: Push
      x-go-package: code.gitea.io/gitea/modules/structs
    NotificationCount:
      description: NotificationCount number of unread notifications
      type: object
      properties:
        new:
          description: New is the number of unread notifications
          type: integer
          format: int64
          x-go-name: New
      x-go-package: code.gitea.io/gitea/modules/structs
    ExternalWiki:
      description: ExternalWiki represents setting for external wiki
      type: object
      properties:
        external_wiki_url:
          description: URL of external wiki.
          type: string
          x-go-name: ExternalWikiURL
      x-go-package: code.gitea.io/gitea/modules/structs
    Organization:
      description: Organization represents an organization
      type: object
      properties:
        avatar_url:
          description: The URL of the organization's avatar
          type: string
          x-go-name: AvatarURL
        description:
          description: The description of the organization
          type: string
          x-go-name: Description
        email:
          description: The email address of the organization
          type: string
          x-go-name: Email
        full_name:
          description: The full display name of the organization
          type: string
          x-go-name: FullName
        id:
          description: The unique identifier of the organization
          type: integer
          format: int64
          x-go-name: ID
        location:
          description: The location of the organization
          type: string
          x-go-name: Location
        name:
          description: The name of the organization
          type: string
          x-go-name: Name
        repo_admin_change_team_access:
          description: Whether repository administrators can change team access
          type: boolean
          x-go-name: RepoAdminChangeTeamAccess
        username:
          description: 'username of the organization

            deprecated'
          type: string
          x-go-name: UserName
        visibility:
          description: The visibility level of the organization (public, limited, private)
          type: string
          x-go-name: Visibility
        website:
          description: The website URL of the organization
          type: string
          x-go-name: Website
      x-go-package: code.gitea.io/gitea/modules/structs
    User:
      description: User represents a user
      type: object
      properties:
        active:
          description: Is user active
          type: boolean
          x-go-name: IsActive
        avatar_url:
          description: URL to the user's avatar
          type: string
          x-go-name: AvatarURL
        created:
          type: string
          format: date-time
          x-go-name: Created
        description:
          description: the user's description
          type: string
          x-go-name: Description
        email:
          type: string
          format: email
          x-go-name: Email
        followers_count:
          description: user counts
          type: integer
          format: int64
          x-go-name: Followers
        following_count:
          type: integer
          format: int64
          x-go-name: Following
        full_name:
          description: the user's full name
          type: string
          x-go-name: FullName
        html_url:
          description: URL to the user's gitea page
          type: string
          x-go-name: HTMLURL
        id:
          description: the user's id
          type: integer
          format: int64
          x-go-name: ID
        is_admin:
          description: Is the user an administrator
          type: boolean
          x-go-name: IsAdmin
        language:
          description: User locale
          type: string
          x-go-name: Language
        last_login:
          type: string
          format: date-time
          x-go-name: LastLogin
        location:
          description: the user's location
          type: string
          x-go-name: Location
        login:
          description: login of the user, same as `username`
          type: string
          x-go-name: UserName
        login_name:
          description: identifier of the user, provided by the external authenticator (if configured)
          type: string
          default: empty
          x-go-name: LoginName
        prohibit_login:
          description: Is user login prohibited
          type: boolean
          x-go-name: ProhibitLogin
        restricted:
          description: Is user restricted
          type: boolean
          x-go-name: Restricted
        source_id:
          description: The ID of the user's Authentication Source
          type: integer
          format: int64
          x-go-name: SourceID
        starred_repos_count:
          type: integer
          format: int64
          x-go-name: StarredRepos
        visibility:
          description: 'User visibility level option: public, limited, private'
          type: string
          x-go-name: Visibility
        website:
          description: the user's website
          type: string
          x-go-name: Website
      x-go-package: code.gitea.io/gitea/modules/structs
    Team:
      description: Team represents a team in an organization
      type: object
      properties:
        can_create_org_repo:
          description: Whether the team can create repositories in the organization
          type: boolean
          x-go-name: CanCreateOrgRepo
        description:
          description: The description of the team
          type: string
          x-go-name: Description
        id:
          description: The unique identifier of the team
          type: integer
          format: int64
          x-go-name: ID
        includes_all_repositories:
          description: Whether the team has access to all repositories in the organization
          type: boolean
          x-go-name: IncludesAllRepositories
        name:
          description: The name of the team
          type: string
          x-go-name: Name
        organization:
          $ref: '#/components/schemas/Organization'
        permission:
          type: string
          enum:
          - none
          - read
          - write
          - admin
          - owner
          x-go-name: Permission
        units:
          type: array
          items:
            type: string
          x-go-name: Units
          example:
          - repo.code
          - repo.issues
          - repo.ext_issues
          - repo.wiki
          - repo.pulls
          - repo.releases
          - repo.projects
          - repo.ext_wiki
        units_map:
          type: object
          additionalProperties:
            type: string
          x-go-name: UnitsMap
          example:
            repo.code: read
            repo.ext_issues: none
            repo.ext_wiki: none
            repo.issues: write
            repo.projects: none
            repo.pulls: owner
            repo.releases: none
            repo.wiki: admin
      x-go-package: code.gitea.io/gitea/modules/structs
    InternalTracker:
      description: InternalTracker represents settings for internal tracker
      type: object
      properties:
        allow_only_contributors_to_track_time:
          description: Let only contributors track time (Built-in issue tracker)
          type: boolean
          x-go-name: AllowOnlyContributorsToTrackTime
        enable_issue_dependencies:
          description: Enable dependencies for issues and pull requests (Built-in issue tracker)
          type: boolean
          x-go-name: EnableIssueDependencies
        enable_time_tracker:
          description: Enable time tracking (Built-in issue tracker)
          type: boolean
          x-go-name: EnableTimeTracker
      x-go-package: code.gitea.io/gitea/modules/structs
    Repository:
      description: Repository represents a repository
      type: object
      properties:
        allow_fast_forward_only_merge:
          type: boolean
          x-go-name: AllowFastForwardOnly
        allow_manual_merge:
          type: boolean
          x-go-name: AllowManualMerge
        allow_merge_commits:
          type: boolean
          x-go-name: AllowMerge
        allow_rebase:
          type: boolean
          x-go-name: AllowRebase
        allow_rebase_explicit:
          type: boolean
          x-go-name: AllowRebaseMerge
        allow_rebase_update:
          type: boolean
          x-go-name: AllowRebaseUpdate
        allow_squash_merge:
          type: boolean
          x-go-name: AllowSquash
        archived:
          type: boolean
          x-go-name: Archived
        archived_at:
          type: string
          format: date-time
          x-go-name: ArchivedAt
        autodetect_manual_merge:
          type: boolean
          x-go-name: AutodetectManualMerge
        avatar_url:
          type: string
          x-go-name: AvatarURL
        branch_count:
          type: integer
          format: int64
          x-go-name: BranchCount
        clone_url:
          type: string
          x-go-name: CloneURL
        created_at:
          type: string
          format: date-time
          x-go-name: Created
        default_allow_maintainer_edit:
          type: boolean
          x-go-name: DefaultAllowMaintainerEdit
        default_branch:
          type: string
          x-go-name: DefaultBranch
        default_delete_branch_after_merge:
          type: boolean
          x-go-name: DefaultDeleteBranchAfterMerge
        default_merge_style:
          type: string
          x-go-name: DefaultMergeStyle
        default_target_branch:
          type: string
          x-go-name: DefaultTargetBranch
        description:
          type: string
          x-go-name: Description
        empty:
          type: boolean
          x-go-name: Empty
        external_tracker:
          $ref: '#/components/schemas/ExternalTracker'
        external_wiki:
          $ref: '#/components/schemas/ExternalWiki'
        fork:
          type: boolean
          x-go-name: Fork
        forks_count:
          type: integer
          format: int64
          x-go-name: Forks
        full_name:
          type: string
          x-go-name: FullName
        has_actions:
          type: boolean
          x-go-name: HasActions
        has_code:
          type: boolean
          x-go-name: HasCode
        has_issues:
          type: boolean
          x-go-name: HasIssues
        has_packages:
          type: boolean
          x-go-name: HasPackages
        has_projects:
          type: boolean
          x-go-name: HasProjects
        has_pull_requests:
          type: boolean
          x-go-name: HasPullRequests
        has_releases:
          type: boolean
          x-go-name: HasReleases
        has_wiki:
          type: boolean
          x-go-name: HasWiki
        html_url:
          type: string
          x-go-name: HTMLURL
        id:
          type: integer
          format: int64
          x-go-name: ID
        ignore_whitespace_conflicts:
          type: boolean
          x-go-name: IgnoreWhitespaceConflicts
        internal:
          type: boolean
          x-go-name: Internal
        internal_tracker:
          $ref: '#/components/schemas/InternalTracker'
        language:
          type: string
          x-go-name: Language
        languages_url:
          type: string
          x-go-name: LanguagesURL
        licenses:
          type: array
          items:
            type: string
          x-go-name: Licenses
        link:
          type: string
          x-go-name: Link
        mirror:
          type: boolean
          x-go-name: Mirror
        mirror_interval:
          type: string
          x-go-name: MirrorInterval
        mirror_updated:
          type: string
          format: date-time
          x-go-name: MirrorUpdated
        name:
          type: string
          x-go-name: Name
        object_format_name:
          description: ObjectFormatName of the underlying git repository
          type: string
          enum:
          - sha1
          - sha256
          x-go-name: ObjectFormatName
        open_issues_count:
          type: integer
          format: int64
          x-go-name: OpenIssues
        open_pr_counter:
          type: integer
          format: int64
          x-go-name: OpenPulls
        original_url:
          type: string
          x-go-name: OriginalURL
        owner:
          $ref: '#/components/schemas/User'
        parent:
          $ref: '#/components/schemas/Repository'
        permissions:
          $ref: '#/components/schemas/Permission'
        private:
          type: boolean
          x-go-name: Private
        projects_mode:
          type: string
          x-go-name: ProjectsMode
        release_counter:
          type: integer
          format: int64
          x-go-name: Releases
        repo_transfer:
          $ref: '#/components/schemas/RepoTransfer'
        size:
          type: integer
          format: int64
          x-go-name: Size
        ssh_url:
          type: string
          x-go-name: SSHURL
        stars_count:
          type: integer
          format: int64
          x-go-name: Stars
        template:
          type: boolean
          x-go-name: Template
        topics:
          type: array
          items:
            type: string
          x-go-name: Topics
        updated_at:
          type: string
          format: date-time
          x-go-name: Updated
        url:
          type: string
          x-go-name: URL
        watchers_count:
          type: integer
          format: int64
          x-go-name: Watchers
        website:
          type: string
          x-go-name: Website
      x-go-package: code.gitea.io/gitea/modules/structs
    NotificationThread:
      description: NotificationThread expose Notification on API
      type: object
      properties:
        id:
          description: ID is the unique identifier for the notification thread
          type: integer
          format: int64
          x-go-name: ID
        pinned:
          description: Pinned indicates if the notification is pinned
          type: boolean
          x-go-name: Pinned
        repository:
          $ref: '#/components/schemas/Repository'
        subject:
          $ref: '#/components/schemas/NotificationSubject'
        unread:
          description: Unread indicates if the notification has been read
          type: boolean
          x-go-name: Unread
        updated_at:
          description: UpdatedAt is the time when the notification was last updated
          type: string
          format: date-time
          x-go-name: UpdatedAt
        url:
          description: URL is the API URL for this notification thread
          type: string
          x-go-name: URL
      x-go-package: code.gitea.io/gitea/modules/structs
    ExternalTracker:
      description: ExternalTracker represents settings for external tracker
      type: object
      properties:
        external_tracker_format:
          description: External Issue Tracker URL Format. Use the placeholders {user}, {repo} and {index} for the username, repository name and issue index.
          type: string
          x-go-name: ExternalTrackerFormat
        external_tracker_regexp_pattern:
          description: External Issue Tracker issue regular expression
          type: string
          x-go-name: ExternalTrackerRegexpPattern
        external_tracker_style:
          description: External Issue Tracker Number Format, either `numeric`, `alphanumeric`, or `regexp`
          type: string
          x-go-name: ExternalTrackerStyle
        external_tracker_url:
          description: URL of external issue tracker.
          type: string
          x-go-name: ExternalTrackerURL
      x-go-package: code.gitea.io/gitea/modules/structs
    NotificationSubject:
      description: NotificationSubject contains the notification subject (Issue/Pull/Commit)
      type: object
      properties:
        html_url:
          description: HTMLURL is the web URL for the notification subject
          type: string
          x-go-name: HTMLURL
        latest_comment_html_url:
          description: LatestCommentHTMLURL is the web URL for the latest comment
          type: string
          x-go-name: LatestCommentHTMLURL
        latest_comment_url:
          description: LatestCommentURL is the API URL for the latest comment
          type: string
          x-go-name: LatestCommentURL
        state:
          description: 'State indicates the current state of the notification subject

            open NotifySubjectStateOpen  NotifySubjectStateOpen is an open subject

            closed NotifySubjectStateClosed  NotifySubjectStateClosed is a closed subject

            merged NotifySubjectStateMerged  NotifySubjectStateMerged is a merged pull request'
          type: string
          enum:
          - open
          - closed
          - merged
          x-go-enum-desc: 'open NotifySubjectStateOpen  NotifySubjectStateOpen is an open subject

            closed NotifySubjectStateClosed  NotifySubjectStateClosed is a closed subject

            merged NotifySubjectStateMerged  NotifySubjectStateMerged is a merged pull request'
          x-go-name: State
        title:
          description: Title is the title of the notification subject
          type: string
          x-go-name: Title
        type:
          description: 'Type indicates the type of the notification subject

            Issue NotifySubjectIssue  NotifySubjectIssue a issue is subject of an notification

            Pull NotifySubjectPull  NotifySubjectPull a pull is subject of an notification

            Commit NotifySubjectCommit  NotifySubjectCommit a commit is subject of an notification

            Repository NotifySubjectRepository  NotifySubjectRepository a repository is subject of an notification'
          type: string
          enum:
          - Issue
          - Pull
          - Commit
          - Repository
          x-go-enum-desc: 'Issue NotifySubjectIssue  NotifySubjectIssue a issue is subject of an notification

            Pull NotifySubjectPull  NotifySubjectPull a pull is subject of an notification

            Commit NotifySubjectCommit  NotifySubjectCommit a commit is subject of an notification

            Repository NotifySubjectRepository  NotifySubjectRepository a repository is subject of an notification'
          x-go-name: Type
        url:
          description: URL is the API URL for the notification subject
          type: string
          x-go-name: URL
      x-go-package: code.gitea.io/gitea/modules/structs
  securitySchemes:
    AccessToken:
      description: This authentication option is deprecated for removal in Gitea 1.23. Please use AuthorizationHeaderToken instead.
      type: apiKey
      name: access_token
      in: query
    AuthorizationHeaderToken:
      description: API tokens must be prepended with "token" followed by a space.
      type: apiKey
      name: Authorization
      in: header
    BasicAuth:
      type: http
      scheme: basic
    SudoHeader:
      description: Sudo API request as the user provided as the key. Admin privileges are required.
      type: apiKey
      name: Sudo
      in: header
    SudoParam:
      description: Sudo API request as the user provided as the key. Admin privileges are required.
      type: apiKey
      name: sudo
      in: query
    TOTPHeader:
      description: Must be used in combination with BasicAuth if two-factor authentication is enabled.
      type: apiKey
      name: X-GITEA-OTP
      in: header
    Token:
      description: This authentication option is deprecated for removal in Gitea 1.23. Please use AuthorizationHeaderToken instead.
      type: apiKey
      name: token
      in: query