> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# Comments API

> Create, list, update, and delete comments on issues and pull requests

## 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:

<ResponseField name="id" type="integer">
  The unique identifier of the comment
</ResponseField>

<ResponseField name="html_url" type="string">
  The web URL for viewing the comment
</ResponseField>

<ResponseField name="pull_request_url" type="string">
  The API URL for the pull request (if applicable)
</ResponseField>

<ResponseField name="issue_url" type="string">
  The API URL for the issue
</ResponseField>

<ResponseField name="user" type="object">
  The user who posted the comment
</ResponseField>

<ResponseField name="original_author" type="string">
  The original author name (for imported comments)
</ResponseField>

<ResponseField name="original_author_id" type="integer">
  The original author ID (for imported comments)
</ResponseField>

<ResponseField name="body" type="string">
  The text content of the comment
</ResponseField>

<ResponseField name="assets" type="array">
  Array of attachment objects (files attached to the comment)
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the comment was created (RFC 3339 format)
</ResponseField>

<ResponseField name="updated_at" type="string">
  Timestamp when the comment was last updated (RFC 3339 format)
</ResponseField>

## Operations

<Tabs>
  <Tab title="List Comments">
    ### 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

    <ParamField path="owner" type="string" required>
      Owner of the repository
    </ParamField>

    <ParamField path="repo" type="string" required>
      Name of the repository
    </ParamField>

    <ParamField path="index" type="integer" required>
      Index number of the issue or pull request
    </ParamField>

    #### Query Parameters

    <ParamField query="since" type="string">
      Only show comments updated after this timestamp (RFC 3339 format)
    </ParamField>

    <ParamField query="before" type="string">
      Only show comments updated before this timestamp (RFC 3339 format)
    </ParamField>

    #### Example Request

    ```bash theme={null}
    curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5/comments" \
      -H "Authorization: token YOUR_ACCESS_TOKEN"
    ```

    #### Response

    ```json theme={null}
    [
      {
        "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"
      }
    ]
    ```
  </Tab>

  <Tab title="Get Comment">
    ### 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

    <ParamField path="owner" type="string" required>
      Owner of the repository
    </ParamField>

    <ParamField path="repo" type="string" required>
      Name of the repository
    </ParamField>

    <ParamField path="id" type="integer" required>
      ID of the comment
    </ParamField>

    #### Example Request

    ```bash theme={null}
    curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/comments/789" \
      -H "Authorization: token YOUR_ACCESS_TOKEN"
    ```

    #### Response

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="Create Comment">
    ### 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

    <ParamField path="owner" type="string" required>
      Owner of the repository
    </ParamField>

    <ParamField path="repo" type="string" required>
      Name of the repository
    </ParamField>

    <ParamField path="index" type="integer" required>
      Index number of the issue or pull request
    </ParamField>

    #### Request Body

    <ParamField body="body" type="string" required>
      The text content of the comment
    </ParamField>

    #### Example Request

    ```bash theme={null}
    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)

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="Update Comment">
    ### 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

    <ParamField path="owner" type="string" required>
      Owner of the repository
    </ParamField>

    <ParamField path="repo" type="string" required>
      Name of the repository
    </ParamField>

    <ParamField path="id" type="integer" required>
      ID of the comment to edit
    </ParamField>

    #### Request Body

    <ParamField body="body" type="string" required>
      The updated text content of the comment
    </ParamField>

    #### Example Request

    ```bash theme={null}
    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)

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="Delete Comment">
    ### 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

    <ParamField path="owner" type="string" required>
      Owner of the repository
    </ParamField>

    <ParamField path="repo" type="string" required>
      Name of the repository
    </ParamField>

    <ParamField path="id" type="integer" required>
      ID of the comment to delete
    </ParamField>

    #### Example Request

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## 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

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

### Query Parameters

<ParamField query="since" type="string">
  Only show comments updated after this timestamp (RFC 3339 format)
</ParamField>

<ParamField query="before" type="string">
  Only show comments updated before this timestamp (RFC 3339 format)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination (1-based)
</ParamField>

<ParamField query="limit" type="integer">
  Number of items per page
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
[
  {
    "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

<ParamField path="owner" type="string" required>
  Owner of the repository
</ParamField>

<ParamField path="repo" type="string" required>
  Name of the repository
</ParamField>

<ParamField path="index" type="integer" required>
  Index number of the issue or pull request
</ParamField>

### Query Parameters

<ParamField query="since" type="string">
  Only show items updated after this timestamp (RFC 3339 format)
</ParamField>

<ParamField query="before" type="string">
  Only show items updated before this timestamp (RFC 3339 format)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer">
  Number of items per page
</ParamField>

### Example Request

```bash theme={null}
curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5/timeline" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"
```

### Response

```json theme={null}
[
  {
    "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

<ResponseField name="id" type="integer">
  The unique identifier of the attachment
</ResponseField>

<ResponseField name="name" type="string">
  The filename of the attachment
</ResponseField>

<ResponseField name="size" type="integer">
  The file size in bytes
</ResponseField>

<ResponseField name="download_url" type="string">
  The URL to download the attachment
</ResponseField>

<ResponseField name="created_at" type="string">
  Timestamp when the attachment was uploaded
</ResponseField>

### Example Comment with Attachments

```json theme={null}
{
  "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

<ResponseField name="403" type="Forbidden">
  User does not have permission to perform the operation, or the issue is locked
</ResponseField>

<ResponseField name="404" type="Not Found">
  Repository, issue, or comment not found
</ResponseField>

<ResponseField name="422" type="Unprocessable Entity">
  Validation error (e.g., missing required `body` field)
</ResponseField>

<ResponseField name="423" type="Locked">
  Repository is archived and cannot be modified
</ResponseField>

## Best Practices

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