Forgejo issue API
The issue API from Forgejo — 33 operation(s) for issue.
The issue API from Forgejo — 33 operation(s) for issue.
swagger: '2.0'
info:
description: This documentation describes the Forgejo API.
title: Forgejo activitypub issue 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: issue
paths:
/repos/issues/search:
get:
produces:
- application/json
tags:
- issue
summary: Search for issues across the repositories that the user has access to
operationId: issueSearchIssues
parameters:
- enum:
- open
- closed
- all
type: string
default: open
description: State of the issue
name: state
in: query
- type: string
description: Comma-separated list of label names. Fetch only issues that have any of these labels. Non existent labels are discarded.
name: labels
in: query
- type: string
description: Comma-separated list of milestone names. Fetch only issues that have any of these milestones. Non existent milestones are discarded.
name: milestones
in: query
- type: string
description: Search string
name: q
in: query
- type: integer
format: int64
description: Repository ID to prioritize in the results
name: priority_repo_id
in: query
- enum:
- issues
- pulls
type: string
description: Filter by issue type
name: type
in: query
- type: string
format: date-time
description: Only show issues updated after the given time (RFC 3339 format)
name: since
in: query
- type: string
format: date-time
description: Only show issues updated before the given time (RFC 3339 format)
name: before
in: query
- type: boolean
default: false
description: Filter issues or pulls assigned to the authenticated user
name: assigned
in: query
- type: boolean
default: false
description: Filter issues or pulls created by the authenticated user
name: created
in: query
- type: boolean
default: false
description: Filter issues or pulls mentioning the authenticated user
name: mentioned
in: query
- type: boolean
default: false
description: Filter pull requests where the authenticated user's review was requested
name: review_requested
in: query
- type: boolean
default: false
description: Filter pull requests reviewed by the authenticated user
name: reviewed
in: query
- type: string
description: Filter by repository owner
name: owner
in: query
- type: string
description: Filter by team (requires organization owner parameter)
name: team
in: query
- minimum: 1
type: integer
default: 1
description: Page number of results to return (1-based)
name: page
in: query
- minimum: 0
type: integer
description: Number of items per page
name: limit
in: query
- enum:
- relevance
- latest
- oldest
- recentupdate
- leastupdate
- mostcomment
- leastcomment
- nearduedate
- farduedate
type: string
default: latest
description: Type of sort
name: sort
in: query
responses:
'200':
$ref: '#/responses/IssueList'
'400':
$ref: '#/responses/error'
'422':
$ref: '#/responses/validationError'
/repos/{owner}/{repo}/issues:
get:
produces:
- application/json
tags:
- issue
summary: List a repository's issues
operationId: issueListIssues
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
- enum:
- closed
- open
- all
type: string
description: whether issue is open or closed
name: state
in: query
- type: string
description: comma separated list of labels. Fetch only issues that have any of this labels. Non existent labels are discarded
name: labels
in: query
- type: string
description: search string
name: q
in: query
- enum:
- issues
- pulls
type: string
description: filter by type (issues / pulls) if set
name: type
in: query
- type: string
description: comma separated list of milestone names or ids. It uses names and fall back to ids. Fetch only issues that have any of this milestones. Non existent milestones are discarded
name: milestones
in: query
- type: string
format: date-time
description: Only show items 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 items updated before the given time. This is a timestamp in RFC 3339 format
name: before
in: query
- type: string
description: Only show items which were created by the given user
name: created_by
in: query
- type: string
description: Only show items for which the given user is assigned
name: assigned_by
in: query
- type: string
description: Only show items in which the given user was mentioned
name: mentioned_by
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
- enum:
- relevance
- latest
- oldest
- recentupdate
- leastupdate
- mostcomment
- leastcomment
- nearduedate
- farduedate
type: string
default: latest
description: Type of sort
name: sort
in: query
responses:
'200':
$ref: '#/responses/IssueList'
'404':
$ref: '#/responses/notFound'
'422':
$ref: '#/responses/validationError'
post:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Create an issue. If using deadline only the date will be taken into account, and time of day ignored.
operationId: issueCreateIssue
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
- name: body
in: body
schema:
$ref: '#/definitions/CreateIssueOption'
responses:
'201':
$ref: '#/responses/Issue'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'412':
$ref: '#/responses/error'
'422':
$ref: '#/responses/validationError'
'423':
$ref: '#/responses/repoArchivedError'
/repos/{owner}/{repo}/issues/comments:
get:
produces:
- application/json
tags:
- issue
summary: List all comments in a repository
operationId: issueGetRepoComments
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: string
format: date-time
description: if provided, only comments updated since the provided time are returned.
name: since
in: query
- type: string
format: date-time
description: if provided, only comments updated before the provided time are returned.
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/CommentList'
'404':
$ref: '#/responses/notFound'
'422':
$ref: '#/responses/validationError'
'500':
$ref: '#/responses/internalServerError'
/repos/{owner}/{repo}/issues/comments/{id}:
get:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Get a comment
operationId: issueGetComment
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: integer
format: int64
description: id of the comment
name: id
in: path
required: true
responses:
'200':
$ref: '#/responses/Comment'
'204':
$ref: '#/responses/empty'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'500':
$ref: '#/responses/internalServerError'
delete:
tags:
- issue
summary: Delete a comment
operationId: issueDeleteComment
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: integer
format: int64
description: id of comment to delete
name: id
in: path
required: true
responses:
'204':
$ref: '#/responses/empty'
'403':
$ref: '#/responses/forbidden'
'500':
$ref: '#/responses/internalServerError'
patch:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Edit a comment
operationId: issueEditComment
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: integer
format: int64
description: id of the comment to edit
name: id
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/EditIssueCommentOption'
responses:
'200':
$ref: '#/responses/Comment'
'204':
$ref: '#/responses/empty'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'423':
$ref: '#/responses/repoArchivedError'
'500':
$ref: '#/responses/internalServerError'
/repos/{owner}/{repo}/issues/comments/{id}/assets:
get:
produces:
- application/json
tags:
- issue
summary: List comment's attachments
operationId: issueListIssueCommentAttachments
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: integer
format: int64
description: id of the comment
name: id
in: path
required: true
responses:
'200':
$ref: '#/responses/AttachmentList'
'404':
$ref: '#/responses/error'
post:
consumes:
- multipart/form-data
produces:
- application/json
tags:
- issue
summary: Create a comment attachment
operationId: issueCreateIssueCommentAttachment
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: integer
format: int64
description: id of the comment
name: id
in: path
required: true
- type: string
description: name of the attachment
name: name
in: query
- type: string
format: date-time
description: time of the attachment's creation. This is a timestamp in RFC 3339 format
name: updated_at
in: query
- type: file
description: attachment to upload
name: attachment
in: formData
required: true
responses:
'201':
$ref: '#/responses/Attachment'
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/error'
'413':
$ref: '#/responses/quotaExceeded'
'422':
$ref: '#/responses/validationError'
'423':
$ref: '#/responses/repoArchivedError'
/repos/{owner}/{repo}/issues/comments/{id}/assets/{attachment_id}:
get:
produces:
- application/json
tags:
- issue
summary: Get a comment attachment
operationId: issueGetIssueCommentAttachment
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: integer
format: int64
description: id of the comment
name: id
in: path
required: true
- type: integer
format: int64
description: id of the attachment to get
name: attachment_id
in: path
required: true
responses:
'200':
$ref: '#/responses/Attachment'
'404':
$ref: '#/responses/error'
delete:
produces:
- application/json
tags:
- issue
summary: Delete a comment attachment
operationId: issueDeleteIssueCommentAttachment
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: integer
format: int64
description: id of the comment
name: id
in: path
required: true
- type: integer
format: int64
description: id of the attachment to delete
name: attachment_id
in: path
required: true
responses:
'204':
$ref: '#/responses/empty'
'404':
$ref: '#/responses/error'
'423':
$ref: '#/responses/repoArchivedError'
patch:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Edit a comment attachment
operationId: issueEditIssueCommentAttachment
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: integer
format: int64
description: id of the comment
name: id
in: path
required: true
- type: integer
format: int64
description: id of the attachment to edit
name: attachment_id
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/EditAttachmentOptions'
responses:
'201':
$ref: '#/responses/Attachment'
'404':
$ref: '#/responses/error'
'413':
$ref: '#/responses/quotaExceeded'
'423':
$ref: '#/responses/repoArchivedError'
/repos/{owner}/{repo}/issues/comments/{id}/reactions:
get:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Get a list of reactions from a comment of an issue
operationId: issueGetCommentReactions
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: integer
format: int64
description: id of the comment to edit
name: id
in: path
required: true
responses:
'200':
$ref: '#/responses/ReactionListWithoutPagination'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
post:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Add a reaction to a comment of an issue
operationId: issuePostCommentReaction
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: integer
format: int64
description: id of the comment to edit
name: id
in: path
required: true
- name: content
in: body
schema:
$ref: '#/definitions/EditReactionOption'
responses:
'200':
$ref: '#/responses/Reaction'
'201':
$ref: '#/responses/Reaction'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
delete:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Remove a reaction from a comment of an issue
operationId: issueDeleteCommentReaction
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: integer
format: int64
description: id of the comment to edit
name: id
in: path
required: true
- name: content
in: body
schema:
$ref: '#/definitions/EditReactionOption'
responses:
'200':
$ref: '#/responses/empty'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/issues/{index}:
get:
produces:
- application/json
tags:
- issue
summary: Get an issue
operationId: issueGetIssue
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: integer
format: int64
description: index of the issue to get
name: index
in: path
required: true
responses:
'200':
$ref: '#/responses/Issue'
'404':
$ref: '#/responses/notFound'
delete:
tags:
- issue
summary: Delete an issue
operationId: issueDelete
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: integer
format: int64
description: index of issue to delete
name: index
in: path
required: true
responses:
'204':
$ref: '#/responses/empty'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
patch:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Edit an issue. If using deadline only the date will be taken into account, and time of day ignored.
operationId: issueEditIssue
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: integer
format: int64
description: index of the issue to edit
name: index
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/EditIssueOption'
responses:
'201':
$ref: '#/responses/Issue'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'412':
$ref: '#/responses/error'
/repos/{owner}/{repo}/issues/{index}/assets:
get:
produces:
- application/json
tags:
- issue
summary: List issue's attachments
operationId: issueListIssueAttachments
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
responses:
'200':
$ref: '#/responses/AttachmentList'
'404':
$ref: '#/responses/error'
post:
consumes:
- multipart/form-data
produces:
- application/json
tags:
- issue
summary: Create an issue attachment
operationId: issueCreateIssueAttachment
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- type: string
description: name of the attachment
name: name
in: query
- type: string
format: date-time
description: time of the attachment's creation. This is a timestamp in RFC 3339 format
name: updated_at
in: query
- type: file
description: attachment to upload
name: attachment
in: formData
required: true
responses:
'201':
$ref: '#/responses/Attachment'
'400':
$ref: '#/responses/error'
'404':
$ref: '#/responses/error'
'413':
$ref: '#/responses/quotaExceeded'
'422':
$ref: '#/responses/validationError'
'423':
$ref: '#/responses/repoArchivedError'
/repos/{owner}/{repo}/issues/{index}/assets/{attachment_id}:
get:
produces:
- application/json
tags:
- issue
summary: Get an issue attachment
operationId: issueGetIssueAttachment
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- type: integer
format: int64
description: id of the attachment to get
name: attachment_id
in: path
required: true
responses:
'200':
$ref: '#/responses/Attachment'
'404':
$ref: '#/responses/error'
delete:
produces:
- application/json
tags:
- issue
summary: Delete an issue attachment
operationId: issueDeleteIssueAttachment
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- type: integer
format: int64
description: id of the attachment to delete
name: attachment_id
in: path
required: true
responses:
'204':
$ref: '#/responses/empty'
'404':
$ref: '#/responses/error'
'423':
$ref: '#/responses/repoArchivedError'
patch:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Edit an issue attachment
operationId: issueEditIssueAttachment
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- type: integer
format: int64
description: id of the attachment to edit
name: attachment_id
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/EditAttachmentOptions'
responses:
'201':
$ref: '#/responses/Attachment'
'404':
$ref: '#/responses/error'
'413':
$ref: '#/responses/quotaExceeded'
'423':
$ref: '#/responses/repoArchivedError'
/repos/{owner}/{repo}/issues/{index}/blocks:
get:
produces:
- application/json
tags:
- issue
summary: List issues that are blocked by this issue
operationId: issueListBlocks
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- 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/IssueListWithoutPagination'
'404':
$ref: '#/responses/notFound'
post:
produces:
- application/json
tags:
- issue
summary: Block the issue given in the body by the issue in path
operationId: issueCreateIssueBlocking
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/IssueMeta'
responses:
'201':
$ref: '#/responses/Issue'
'404':
description: the issue does not exist
delete:
produces:
- application/json
tags:
- issue
summary: Unblock the issue given in the body by the issue in path
operationId: issueRemoveIssueBlocking
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/IssueMeta'
responses:
'200':
$ref: '#/responses/Issue'
'404':
$ref: '#/responses/notFound'
/repos/{owner}/{repo}/issues/{index}/comments:
get:
produces:
- application/json
tags:
- issue
summary: List all comments on an issue
operationId: issueGetComments
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- type: string
format: date-time
description: if provided, only comments updated since the specified time are returned.
name: since
in: query
- type: string
format: date-time
description: if provided, only comments updated before the provided time are returned.
name: before
in: query
responses:
'200':
$ref: '#/responses/CommentList'
'404':
$ref: '#/responses/notFound'
'422':
$ref: '#/responses/validationError'
'500':
$ref: '#/responses/internalServerError'
post:
consumes:
- application/json
produces:
- application/json
tags:
- issue
summary: Add a comment to an issue
operationId: issueCreateComment
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: integer
format: int64
description: index of the issue
name: index
in: path
required: true
- name: body
in: body
schema:
$ref: '#/definitions/CreateIssueCommentOption'
responses:
'201':
$ref: '#/responses/Comment'
'403':
$ref: '#/responses/forbidden'
'404':
$ref: '#/responses/notFound'
'423':
$ref: '#/responses/repoArchivedError'
'500':
$ref: '#/responses/internalServerError'
/repos/{owner}/{repo}/issues/{index}/comments/{id}:
delete:
tags:
- issue
summary: Delete a comment
operationId: issueDeleteCommentDeprecated
deprecated: true
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: integer
description: this parameter is ignored
name: index
in: path
required: true
- type: integer
format: int64
description: id of comment to delete
name: id
in: path
required: true
responses:
'204':
$ref: '#/responses/empt
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/forgejo/refs/heads/main/openapi/forgejo-issue-api-openapi.yml