Comments API

Overview

The Comments API allows you to manage comments on both issues and pull requests. Comments provide a way for users to discuss and collaborate on issues and PRs.

Comment Object

The Comment object represents a comment with the following structure:

integer

The unique identifier of the comment

html_url

string

The web URL for viewing the comment

pull_request_url

string

The API URL for the pull request (if applicable)

issue_url

string

The API URL for the issue

user

object

The user who posted the comment

original_author

string

The original author name (for imported comments)

original_author_id

integer

The original author ID (for imported comments)

body

string

The text content of the comment

assets

array

Array of attachment objects (files attached to the comment)

created_at

string

Timestamp when the comment was created (RFC 3339 format)

updated_at

string

Timestamp when the comment was last updated (RFC 3339 format)

Operations

List Comments
Get Comment
Create Comment
Update Comment
Delete Comment

List Issue Comments

List all comments on a specific issue or pull request.Endpoint: GET /api/v1/repos/{owner}/{repo}/issues/{index}/comments

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

index

integer

required

Index number of the issue or pull request

Query Parameters

since

string

Only show comments updated after this timestamp (RFC 3339 format)

before

string

Only show comments updated before this timestamp (RFC 3339 format)

Example Request

curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5/comments" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

[
  {
    "id": 789,
    "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-789",
    "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5",
    "user": {
      "id": 2,
      "login": "johndoe",
      "full_name": "John Doe"
    },
    "body": "I think we should handle this edge case differently.",
    "assets": [],
    "created_at": "2024-01-15T14:30:00Z",
    "updated_at": "2024-01-15T14:30:00Z"
  },
  {
    "id": 790,
    "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-790",
    "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5",
    "user": {
      "id": 1,
      "login": "admin",
      "full_name": "Admin User"
    },
    "body": "Good point! I'll update the implementation.",
    "assets": [],
    "created_at": "2024-01-15T15:00:00Z",
    "updated_at": "2024-01-15T15:00:00Z"
  }
]

Get a Single Comment

Retrieve details of a specific comment by its ID.Endpoint: GET /api/v1/repos/{owner}/{repo}/issues/comments/{id}

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

integer

required

ID of the comment

Example Request

curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/comments/789" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

{
  "id": 789,
  "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-789",
  "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5",
  "user": {
    "id": 2,
    "login": "johndoe"
  },
  "body": "I think we should handle this edge case differently.",
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z"
}

Create a Comment

Add a new comment to an issue or pull request.Endpoint: POST /api/v1/repos/{owner}/{repo}/issues/{index}/comments

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

index

integer

required

Index number of the issue or pull request

Request Body

body

string

required

The text content of the comment

Example Request

curl -X POST "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5/comments" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "This looks great! Ready to merge after CI passes."
  }'

Response (201 Created)

{
  "id": 791,
  "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-791",
  "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5",
  "user": {
    "id": 3,
    "login": "reviewer",
    "full_name": "Reviewer User"
  },
  "body": "This looks great! Ready to merge after CI passes.",
  "assets": [],
  "created_at": "2024-01-16T10:00:00Z",
  "updated_at": "2024-01-16T10:00:00Z"
}

Edit a Comment

Modify an existing comment. Only the comment author or repository maintainers can edit comments.Endpoint: PATCH /api/v1/repos/{owner}/{repo}/issues/comments/{id}

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

integer

required

ID of the comment to edit

Request Body

body

string

required

The updated text content of the comment

Example Request

curl -X PATCH "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/comments/791" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "This looks great! Ready to merge after CI passes. LGTM!"
  }'

Response (200 OK)

{
  "id": 791,
  "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-791",
  "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5",
  "user": {
    "id": 3,
    "login": "reviewer"
  },
  "body": "This looks great! Ready to merge after CI passes. LGTM!",
  "created_at": "2024-01-16T10:00:00Z",
  "updated_at": "2024-01-16T10:15:00Z"
}

Delete a Comment

Permanently delete a comment. Only the comment author or repository maintainers can delete comments.Endpoint: DELETE /api/v1/repos/{owner}/{repo}/issues/comments/{id}

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

integer

required

ID of the comment to delete

Example Request

curl -X DELETE "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/comments/791" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response (204 No Content)

No response body is returned on successful deletion.

List Repository Comments

List all comments across all issues and pull requests in a repository. Endpoint: GET /api/v1/repos/{owner}/{repo}/issues/comments

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

Query Parameters

since

string

Only show comments updated after this timestamp (RFC 3339 format)

before

string

Only show comments updated before this timestamp (RFC 3339 format)

page

integer

default:"1"

Page number for pagination (1-based)

limit

integer

Number of items per page

Example Request

curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/comments?since=2024-01-01T00:00:00Z" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

[
  {
    "id": 789,
    "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-789",
    "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5",
    "user": {
      "id": 2,
      "login": "johndoe"
    },
    "body": "Comment on issue #5",
    "created_at": "2024-01-15T14:30:00Z"
  },
  {
    "id": 792,
    "html_url": "https://gitea.example.com/myorg/myrepo/issues/12#issuecomment-792",
    "pull_request_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls/12",
    "issue_url": "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/12",
    "user": {
      "id": 3,
      "login": "reviewer"
    },
    "body": "Comment on PR #12",
    "created_at": "2024-01-16T11:00:00Z"
  }
]

Timeline Comments

Get all comments and events on an issue or pull request in timeline order. This includes not just regular comments, but also system events like labels being added, state changes, etc. Endpoint: GET /api/v1/repos/{owner}/{repo}/issues/{index}/timeline

Path Parameters

owner

string

required

Owner of the repository

repo

string

required

Name of the repository

index

integer

required

Index number of the issue or pull request

Query Parameters

since

string

Only show items updated after this timestamp (RFC 3339 format)

before

string

Only show items updated before this timestamp (RFC 3339 format)

page

integer

default:"1"

Page number for pagination

limit

integer

Number of items per page

Example Request

curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5/timeline" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

[
  {
    "id": 100,
    "type": "comment",
    "html_url": "https://gitea.example.com/myorg/myrepo/issues/5#issuecomment-789",
    "user": {
      "id": 2,
      "login": "johndoe"
    },
    "body": "I think we should handle this edge case differently.",
    "created_at": "2024-01-15T14:30:00Z"
  },
  {
    "id": 101,
    "type": "label",
    "user": {
      "id": 1,
      "login": "admin"
    },
    "label": {
      "id": 1,
      "name": "bug",
      "color": "ee0701"
    },
    "created_at": "2024-01-15T14:35:00Z"
  },
  {
    "id": 102,
    "type": "state_change",
    "user": {
      "id": 1,
      "login": "admin"
    },
    "body": "closed",
    "created_at": "2024-01-16T09:00:00Z"
  }
]

Comment Attachments

Comments can have file attachments. The assets field in the comment object contains an array of attachment objects.

Attachment Object Structure

integer

The unique identifier of the attachment

name

string

The filename of the attachment

size

integer

The file size in bytes

download_url

string

The URL to download the attachment

created_at

string

Timestamp when the attachment was uploaded

Example Comment with Attachments

{
  "id": 793,
  "user": {
    "id": 2,
    "login": "johndoe"
  },
  "body": "Here's a screenshot of the bug:",
  "assets": [
    {
      "id": 50,
      "name": "screenshot.png",
      "size": 245678,
      "download_url": "https://gitea.example.com/attachments/uuid-here/screenshot.png",
      "created_at": "2024-01-17T10:00:00Z"
    }
  ],
  "created_at": "2024-01-17T10:00:00Z"
}

Permissions

Reading Comments

Users can read comments on issues and pull requests they have access to
Public repositories: anyone can read comments
Private repositories: only members with read access can read comments

Creating Comments

Authenticated users with read access can create comments
Comments cannot be added to locked issues unless the user is a maintainer or admin

Editing Comments

Comment authors can edit their own comments
Repository maintainers and admins can edit any comment

Deleting Comments

Comment authors can delete their own comments
Repository maintainers and admins can delete any comment

Error Responses

403

Forbidden

User does not have permission to perform the operation, or the issue is locked

404

Not Found

Repository, issue, or comment not found

422

Unprocessable Entity

Validation error (e.g., missing required body field)

423

Locked

Repository is archived and cannot be modified

Best Practices

Pagination: Always use pagination when listing comments for issues with many comments
Rate Limiting: Be aware of API rate limits when creating multiple comments
Markdown: Comment bodies support Markdown formatting
Mentions: Use @username to mention users in comments
References: Use #123 to reference other issues or pull requests
Timestamps: Use the since and before parameters to filter comments by time range
Attachments: Upload attachments separately and reference them in comment body if needed

Overview

Repositories

Issues & Pull Requests

Organizations & Teams

Users

Actions & Packages

​Overview

​Comment Object

​Operations

​List Issue Comments

​Path Parameters

​Query Parameters

​Example Request

​Response

​Get a Single Comment

​Path Parameters

​Example Request

​Response

​Create a Comment

​Path Parameters

​Request Body

​Example Request

​Response (201 Created)

​Edit a Comment

​Path Parameters

​Request Body

​Example Request

​Response (200 OK)

​Delete a Comment

​Path Parameters

​Example Request

​Response (204 No Content)

​List Repository Comments

​Path Parameters

​Query Parameters

​Example Request

​Response

​Timeline Comments

​Path Parameters

​Query Parameters

​Example Request

​Response

​Comment Attachments

​Attachment Object Structure

​Example Comment with Attachments

​Permissions

​Reading Comments

​Creating Comments

​Editing Comments

​Deleting Comments

​Error Responses

​Best Practices

Build docs developers (and LLMs) love

Overview

Comment Object

Operations

List Issue Comments

Path Parameters

Query Parameters

Example Request

Response

Get a Single Comment

Path Parameters

Example Request

Response

Create a Comment

Path Parameters

Request Body

Example Request

Response (201 Created)

Edit a Comment

Path Parameters

Request Body

Example Request

Response (200 OK)

Delete a Comment

Path Parameters

Example Request

Response (204 No Content)

List Repository Comments

Path Parameters

Query Parameters

Example Request

Response

Timeline Comments

Path Parameters

Query Parameters

Example Request

Response

Comment Attachments

Attachment Object Structure

Example Comment with Attachments

Permissions

Reading Comments

Creating Comments

Editing Comments

Deleting Comments

Error Responses

Best Practices