swagger: '2.0'
info:
  description: This documentation describes the Forgejo API.
  title: Forgejo activitypub notification API
  license:
    name: This file is distributed under the MIT license for the purpose of interoperability
    url: http://opensource.org/licenses/MIT
  version: 16.0.0-dev-465-4b83448b7d+gitea-1.22.0
basePath: /api/v1
schemes:
- https
- http
consumes:
- application/json
- text/plain
produces:
- application/json
- text/html
security:
- BasicAuth: []
- AuthorizationHeaderToken: []
- SudoParam: []
- SudoHeader: []
- TOTPHeader: []
tags:
- name: notification
paths:
  /notifications:
    get:
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - notification
      summary: List users's notification threads
      operationId: notifyGetList
      parameters:
      - type: boolean
        description: If true, show notifications marked as read. Default value is false
        name: all
        in: query
      - type: array
        items:
          type: string
        collectionFormat: multi
        description: 'Show notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread & pinned.'
        name: status-types
        in: query
      - type: array
        items:
          enum:
          - issue
          - pull
          - repository
          type: string
        collectionFormat: multi
        description: filter notifications by subject type
        name: subject-type
        in: query
      - type: string
        format: date-time
        description: Only show notifications updated after the given time. This is a timestamp in RFC 3339 format
        name: since
        in: query
      - 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
      - type: integer
        description: page number of results to return (1-based)
        name: page
        in: query
      - type: integer
        description: page size of results
        name: limit
        in: query
      responses:
        '200':
          $ref: '#/responses/NotificationThreadList'
    put:
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - notification
      summary: Mark notification threads as read, pinned or unread
      operationId: notifyReadList
      parameters:
      - type: string
        format: date-time
        description: Describes the last point that notifications were checked. Anything updated since this time will not be updated.
        name: last_read_at
        in: query
      - type: boolean
        description: If true, mark all notifications on this repo. Default value is false
        name: all
        in: query
      - type: array
        items:
          type: string
        collectionFormat: multi
        description: 'Mark notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread.'
        name: status-types
        in: query
      - type: string
        description: Status to mark notifications as, Defaults to read.
        name: to-status
        in: query
      responses:
        '205':
          $ref: '#/responses/NotificationThreadListWithoutPagination'
  /notifications/new:
    get:
      tags:
      - notification
      summary: Check if unread notifications exist
      operationId: notifyNewAvailable
      responses:
        '200':
          $ref: '#/responses/NotificationCount'
  /notifications/threads/{id}:
    get:
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - notification
      summary: Get notification thread by ID
      operationId: notifyGetThread
      parameters:
      - type: integer
        format: int64
        description: id of notification thread
        name: id
        in: path
        required: true
      responses:
        '200':
          $ref: '#/responses/NotificationThread'
        '403':
          $ref: '#/responses/forbidden'
        '404':
          $ref: '#/responses/notFound'
    patch:
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - notification
      summary: Mark notification thread as read by ID
      operationId: notifyReadThread
      parameters:
      - type: integer
        format: int64
        description: id of notification thread
        name: id
        in: path
        required: true
      - type: string
        default: read
        description: Status to mark notifications as
        name: to-status
        in: query
      responses:
        '205':
          $ref: '#/responses/NotificationThread'
        '403':
          $ref: '#/responses/forbidden'
        '404':
          $ref: '#/responses/notFound'
  /repos/{owner}/{repo}/notifications:
    get:
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - notification
      summary: List users's notification threads on a specific repo
      operationId: notifyGetRepoList
      parameters:
      - type: string
        description: owner of the repo
        name: owner
        in: path
        required: true
      - type: string
        description: name of the repo
        name: repo
        in: path
        required: true
      - type: boolean
        description: If true, show notifications marked as read. Default value is false
        name: all
        in: query
      - type: array
        items:
          type: string
        collectionFormat: multi
        description: 'Show notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread & pinned'
        name: status-types
        in: query
      - type: array
        items:
          enum:
          - issue
          - pull
          - repository
          type: string
        collectionFormat: multi
        description: filter notifications by subject type
        name: subject-type
        in: query
      - type: string
        format: date-time
        description: Only show notifications updated after the given time. This is a timestamp in RFC 3339 format
        name: since
        in: query
      - 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
      - type: integer
        description: page number of results to return (1-based)
        name: page
        in: query
      - type: integer
        description: page size of results
        name: limit
        in: query
      responses:
        '200':
          $ref: '#/responses/NotificationThreadList'
    put:
      consumes:
      - application/json
      produces:
      - application/json
      tags:
      - notification
      summary: Mark notification threads as read, pinned or unread on a specific repo
      operationId: notifyReadRepoList
      parameters:
      - type: string
        description: owner of the repo
        name: owner
        in: path
        required: true
      - type: string
        description: name of the repo
        name: repo
        in: path
        required: true
      - type: boolean
        description: If true, mark all notifications on this repo. Default value is false
        name: all
        in: query
      - type: array
        items:
          type: string
        collectionFormat: multi
        description: 'Mark notifications with the provided status types. Options are: unread, read and/or pinned. Defaults to unread.'
        name: status-types
        in: query
      - type: string
        description: Status to mark notifications as. Defaults to read.
        name: to-status
        in: query
      - type: string
        format: date-time
        description: Describes the last point that notifications were checked. Anything updated since this time will not be updated.
        name: last_read_at
        in: query
      responses:
        '205':
          $ref: '#/responses/NotificationThreadListWithoutPagination'
definitions:
  Team:
    description: Team represents a team in an organization
    type: object
    properties:
      can_create_org_repo:
        type: boolean
        x-go-name: CanCreateOrgRepo
      description:
        type: string
        x-go-name: Description
      id:
        type: integer
        format: int64
        x-go-name: ID
      includes_all_repositories:
        type: boolean
        x-go-name: IncludesAllRepositories
      name:
        type: string
        x-go-name: Name
      organization:
        $ref: '#/definitions/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.actions: none
          repo.code: read
          repo.ext_issues: none
          repo.ext_wiki: none
          repo.issues: write
          repo.packages: none
          repo.projects: none
          repo.pulls: owner
          repo.releases: none
          repo.wiki: admin
    x-go-package: forgejo.org/modules/structs
  Organization:
    description: Organization represents an organization
    type: object
    properties:
      avatar_url:
        type: string
        x-go-name: AvatarURL
      created:
        type: string
        format: date-time
        x-go-name: Created
      description:
        type: string
        x-go-name: Description
      email:
        type: string
        x-go-name: Email
      full_name:
        type: string
        x-go-name: FullName
      id:
        type: integer
        format: int64
        x-go-name: ID
      location:
        type: string
        x-go-name: Location
      name:
        type: string
        x-go-name: Name
      repo_admin_change_team_access:
        type: boolean
        x-go-name: RepoAdminChangeTeamAccess
      username:
        description: deprecated
        type: string
        x-go-name: UserName
      visibility:
        type: string
        x-go-name: Visibility
      website:
        type: string
        x-go-name: Website
    x-go-package: forgejo.org/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: forgejo.org/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 profile 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: the user's username
        type: string
        x-go-name: UserName
      login_name:
        description: the user's authentication sign-in name.
        type: string
        default: empty
        x-go-name: LoginName
      prohibit_login:
        description: Is user login prohibited
        type: boolean
        x-go-name: ProhibitLogin
      pronouns:
        description: the user's pronouns
        type: string
        x-go-name: Pronouns
      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: forgejo.org/modules/structs
  APIForbiddenError:
    type: object
    properties:
      message:
        type: string
        x-go-name: Message
      url:
        type: string
        x-go-name: URL
    x-go-package: forgejo.org/services/context
  APINotFound:
    type: object
    properties:
      errors:
        type: array
        items:
          type: string
        x-go-name: Errors
      message:
        type: string
        x-go-name: Message
      url:
        type: string
        x-go-name: URL
    x-go-package: forgejo.org/services/context
  NotificationSubject:
    description: NotificationSubject contains the notification subject (Issue/Pull/Commit)
    type: object
    properties:
      html_url:
        type: string
        x-go-name: HTMLURL
      latest_comment_html_url:
        type: string
        x-go-name: LatestCommentHTMLURL
      latest_comment_url:
        type: string
        x-go-name: LatestCommentURL
      state:
        $ref: '#/definitions/StateType'
      title:
        type: string
        x-go-name: Title
      type:
        $ref: '#/definitions/NotifySubjectType'
      url:
        type: string
        x-go-name: URL
    x-go-package: forgejo.org/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: forgejo.org/modules/structs
  NotifySubjectType:
    description: NotifySubjectType represent type of notification subject
    type: string
    x-go-package: forgejo.org/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: forgejo.org/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: forgejo.org/modules/structs
  RepoTransfer:
    description: RepoTransfer represents a pending repo transfer
    type: object
    properties:
      doer:
        $ref: '#/definitions/User'
      recipient:
        $ref: '#/definitions/User'
      teams:
        type: array
        items:
          $ref: '#/definitions/Team'
        x-go-name: Teams
    x-go-package: forgejo.org/modules/structs
  StateType:
    description: StateType issue state type
    type: string
    x-go-package: forgejo.org/modules/structs
  Repository:
    description: Repository represents a repository
    type: object
    properties:
      allow_fast_forward_only_merge:
        type: boolean
        x-go-name: AllowFastForwardOnly
      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
      avatar_url:
        type: string
        x-go-name: AvatarURL
      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_update_style:
        type: string
        x-go-name: DefaultUpdateStyle
      description:
        type: string
        x-go-name: Description
      empty:
        type: boolean
        x-go-name: Empty
      external_tracker:
        $ref: '#/definitions/ExternalTracker'
      external_wiki:
        $ref: '#/definitions/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
      globally_editable_wiki:
        type: boolean
        x-go-name: GloballyEditableWiki
      has_actions:
        type: boolean
        x-go-name: HasActions
      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:
        description: is the wiki enabled
        type: boolean
        x-go-name: HasWiki
      has_wiki_contents:
        description: have wiki pages ever been created
        type: boolean
        x-go-name: HasWikiContents
      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: '#/definitions/InternalTracker'
      language:
        type: string
        x-go-name: Language
      languages_url:
        type: string
        x-go-name: LanguagesURL
      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: '#/definitions/User'
      parent:
        $ref: '#/definitions/Repository'
      permissions:
        $ref: '#/definitions/Permission'
      private:
        type: boolean
        x-go-name: Private
      release_counter:
        type: integer
        format: int64
        x-go-name: Releases
      repo_transfer:
        $ref: '#/definitions/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
      wiki_branch:
        type: string
        x-go-name: WikiBranch
      wiki_clone_url:
        type: string
        x-go-name: WikiCloneURL
      wiki_ssh_url:
        type: string
        x-go-name: WikiSSHURL
    x-go-package: forgejo.org/modules/structs
  NotificationThread:
    description: NotificationThread expose Notification on API
    type: object
    properties:
      id:
        type: integer
        format: int64
        x-go-name: ID
      pinned:
        type: boolean
        x-go-name: Pinned
      repository:
        $ref: '#/definitions/Repository'
      subject:
        $ref: '#/definitions/NotificationSubject'
      unread:
        type: boolean
        x-go-name: Unread
      updated_at:
        type: string
        format: date-time
        x-go-name: UpdatedAt
      url:
        type: string
        x-go-name: URL
    x-go-package: forgejo.org/modules/structs
  NotificationCount:
    description: NotificationCount number of unread notifications
    type: object
    properties:
      new:
        type: integer
        format: int64
        x-go-name: New
    x-go-package: forgejo.org/modules/structs
responses:
  NotificationThreadListWithoutPagination:
    description: NotificationThreadListWithoutPagination - Notification threads without pagination headers
    schema:
      type: array
      items:
        $ref: '#/definitions/NotificationThread'
  forbidden:
    description: APIForbiddenError is a forbidden error response
    schema:
      $ref: '#/definitions/APIForbiddenError'
  NotificationThreadList:
    description: NotificationThreadList
    schema:
      type: array
      items:
        $ref: '#/definitions/NotificationThread'
    headers:
      X-Total-Count:
        type: integer
        format: int64
        description: The total number of notification threads
  NotificationThread:
    description: NotificationThread
    schema:
      $ref: '#/definitions/NotificationThread'
  NotificationCount:
    description: Number of unread notifications
    schema:
      $ref: '#/definitions/NotificationCount'
  notFound:
    description: APINotFound is a not found error response
    schema:
      $ref: '#/definitions/APINotFound'
securityDefinitions:
  AuthorizationHeaderToken:
    description: API tokens must be prepended with "token" followed by a space.
    type: apiKey
    name: Authorization
    in: header
  BasicAuth:
    type: 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-FORGEJO-OTP
    in: header