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

# Issues API

> Create, list, update, and manage issues in your Gitea repositories

## Overview

The Issues API allows you to manage repository issues including creating, listing, updating, closing, and deleting issues. Issues can have assignees, labels, milestones, and deadlines.

## Issue Object

The Issue object represents an issue in a repository with the following structure:

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

<ResponseField name="number" type="integer">
  The issue number (index) in the repository
</ResponseField>

<ResponseField name="title" type="string">
  The title of the issue
</ResponseField>

<ResponseField name="body" type="string">
  The description body content of the issue
</ResponseField>

<ResponseField name="state" type="string" default="open">
  The current state of the issue. Possible values: `open`, `closed`
</ResponseField>

<ResponseField name="user" type="object">
  The user who created the issue
</ResponseField>

<ResponseField name="labels" type="array">
  Array of label objects attached to the issue
</ResponseField>

<ResponseField name="assignees" type="array">
  Array of user objects assigned to the issue
</ResponseField>

<ResponseField name="milestone" type="object">
  The milestone associated with the issue
</ResponseField>

<ResponseField name="comments" type="integer">
  The number of comments on the issue
</ResponseField>

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

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

<ResponseField name="closed_at" type="string">
  Timestamp when the issue was closed (RFC 3339 format)
</ResponseField>

<ResponseField name="due_date" type="string">
  The deadline for the issue (RFC 3339 format)
</ResponseField>

## Operations

<Tabs>
  <Tab title="List Issues">
    ### List Repository Issues

    List all issues in a specific repository.

    **Endpoint:** `GET /api/v1/repos/{owner}/{repo}/issues`

    #### 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="state" type="string" default="open">
      Filter by issue state. Options: `open`, `closed`, `all`
    </ParamField>

    <ParamField query="labels" type="string">
      Comma-separated list of label names to filter by
    </ParamField>

    <ParamField query="milestones" type="string">
      Comma-separated list of milestone names or IDs to filter by
    </ParamField>

    <ParamField query="q" type="string">
      Search query string
    </ParamField>

    <ParamField query="type" type="string">
      Filter by type. Options: `issues`, `pulls`
    </ParamField>

    <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="created_by" type="string">
      Filter by creator username
    </ParamField>

    <ParamField query="assigned_by" type="string">
      Filter by assignee username
    </ParamField>

    <ParamField query="mentioned_by" type="string">
      Filter by mentioned username
    </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?state=open&labels=bug,enhancement" \
      -H "Authorization: token YOUR_ACCESS_TOKEN"
    ```

    #### Response

    ```json theme={null}
    [
      {
        "id": 123,
        "number": 5,
        "title": "Fix login bug",
        "body": "Users are unable to login with special characters",
        "state": "open",
        "user": {
          "id": 1,
          "login": "johndoe",
          "full_name": "John Doe"
        },
        "labels": [
          {
            "id": 10,
            "name": "bug",
            "color": "ee0701"
          }
        ],
        "assignees": [],
        "milestone": null,
        "comments": 3,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-16T14:20:00Z",
        "closed_at": null,
        "due_date": null
      }
    ]
    ```
  </Tab>

  <Tab title="Get Issue">
    ### Get a Single Issue

    Retrieve details of a specific issue by its index number.

    **Endpoint:** `GET /api/v1/repos/{owner}/{repo}/issues/{index}`

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

    #### Example Request

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

    #### Response

    ```json theme={null}
    {
      "id": 123,
      "number": 5,
      "title": "Fix login bug",
      "body": "Users are unable to login with special characters",
      "state": "open",
      "user": {
        "id": 1,
        "login": "johndoe"
      },
      "labels": [],
      "assignees": [],
      "milestone": null,
      "comments": 0,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    }
    ```
  </Tab>

  <Tab title="Create Issue">
    ### Create an Issue

    Create a new issue in a repository. If using a deadline, only the date will be taken into account, and time of day will be ignored.

    **Endpoint:** `POST /api/v1/repos/{owner}/{repo}/issues`

    #### Path Parameters

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

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

    #### Request Body

    <ParamField body="title" type="string" required>
      The title of the issue
    </ParamField>

    <ParamField body="body" type="string">
      The description body content of the issue
    </ParamField>

    <ParamField body="ref" type="string">
      Reference to a branch or commit
    </ParamField>

    <ParamField body="assignees" type="array">
      Array of usernames to assign to the issue
    </ParamField>

    <ParamField body="labels" type="array">
      Array of label IDs to attach to the issue
    </ParamField>

    <ParamField body="milestone" type="integer">
      Milestone ID to associate with the issue
    </ParamField>

    <ParamField body="due_date" type="string">
      Deadline for the issue (RFC 3339 format)
    </ParamField>

    <ParamField body="closed" type="boolean" default="false">
      Whether to create the issue in closed state
    </ParamField>

    #### Example Request

    ```bash theme={null}
    curl -X POST "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues" \
      -H "Authorization: token YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Add user authentication",
        "body": "Implement OAuth2 authentication for users",
        "labels": [1, 3],
        "assignees": ["johndoe"],
        "milestone": 2
      }'
    ```

    #### Response (201 Created)

    ```json theme={null}
    {
      "id": 124,
      "number": 6,
      "title": "Add user authentication",
      "body": "Implement OAuth2 authentication for users",
      "state": "open",
      "user": {
        "id": 1,
        "login": "admin"
      },
      "labels": [
        {
          "id": 1,
          "name": "enhancement"
        }
      ],
      "assignees": [
        {
          "id": 2,
          "login": "johndoe"
        }
      ],
      "milestone": {
        "id": 2,
        "title": "v1.0"
      },
      "comments": 0,
      "created_at": "2024-01-17T09:00:00Z",
      "updated_at": "2024-01-17T09:00:00Z"
    }
    ```
  </Tab>

  <Tab title="Update Issue">
    ### Update an Issue

    Modify an existing issue. If using a deadline, only the date will be taken into account, and time of day will be ignored.

    **Endpoint:** `PATCH /api/v1/repos/{owner}/{repo}/issues/{index}`

    #### 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 to update
    </ParamField>

    #### Request Body

    <ParamField body="title" type="string">
      New title for the issue
    </ParamField>

    <ParamField body="body" type="string">
      New description body content
    </ParamField>

    <ParamField body="state" type="string">
      New state for the issue. Options: `open`, `closed`
    </ParamField>

    <ParamField body="assignees" type="array">
      New array of assignee usernames (replaces existing assignees)
    </ParamField>

    <ParamField body="milestone" type="integer">
      New milestone ID (use 0 to remove milestone)
    </ParamField>

    <ParamField body="due_date" type="string">
      New deadline (RFC 3339 format)
    </ParamField>

    <ParamField body="unset_due_date" type="boolean">
      Set to `true` to remove the deadline
    </ParamField>

    #### Example Request

    ```bash theme={null}
    curl -X PATCH "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/6" \
      -H "Authorization: token YOUR_ACCESS_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Add OAuth2 authentication",
        "state": "closed",
        "body": "Implementation completed and merged."
      }'
    ```

    #### Response (201 Created)

    ```json theme={null}
    {
      "id": 124,
      "number": 6,
      "title": "Add OAuth2 authentication",
      "body": "Implementation completed and merged.",
      "state": "closed",
      "closed_at": "2024-01-20T15:30:00Z",
      "updated_at": "2024-01-20T15:30:00Z"
    }
    ```
  </Tab>

  <Tab title="Delete Issue">
    ### Delete an Issue

    Permanently delete an issue from a repository.

    **Endpoint:** `DELETE /api/v1/repos/{owner}/{repo}/issues/{index}`

    #### 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 to delete
    </ParamField>

    #### Example Request

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

    #### Response (204 No Content)

    No response body is returned on successful deletion.
  </Tab>
</Tabs>

## Search Issues

Search for issues across all repositories the authenticated user has access to.

**Endpoint:** `GET /api/v1/repos/issues/search`

### Query Parameters

<ParamField query="state" type="string" default="open">
  State of the issue. Options: `open`, `closed`, `all`
</ParamField>

<ParamField query="labels" type="string">
  Comma-separated list of label names
</ParamField>

<ParamField query="milestones" type="string">
  Comma-separated list of milestone names
</ParamField>

<ParamField query="q" type="string">
  Search query string
</ParamField>

<ParamField query="type" type="string">
  Filter by type. Options: `issues`, `pulls`
</ParamField>

<ParamField query="owner" type="string">
  Filter by repository owner
</ParamField>

<ParamField query="created_by" type="string">
  Filter by creator username
</ParamField>

<ParamField query="assigned" type="boolean">
  Filter issues assigned to the authenticated user
</ParamField>

<ParamField query="created" type="boolean">
  Filter issues created by the authenticated user
</ParamField>

<ParamField query="mentioned" type="boolean">
  Filter issues mentioning the authenticated user
</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/issues/search?q=authentication&state=open&assigned=true" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"
```

### Response

```json theme={null}
[
  {
    "id": 125,
    "number": 7,
    "title": "Improve authentication flow",
    "repository": {
      "id": 10,
      "name": "backend",
      "owner": "myorg",
      "full_name": "myorg/backend"
    },
    "state": "open",
    "created_at": "2024-01-18T12:00:00Z"
  }
]
```

## Update Issue Deadline

Set or update the deadline for an issue. If set to null, the deadline is deleted.

**Endpoint:** `POST /api/v1/repos/{owner}/{repo}/issues/{index}/deadline`

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

### Request Body

<ParamField body="due_date" type="string" required>
  The new deadline (RFC 3339 format) or `null` to remove
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://gitea.example.com/api/v1/repos/myorg/myrepo/issues/5/deadline" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2024-02-01T00:00:00Z"
  }'
```

### Response (201 Created)

```json theme={null}
{
  "due_date": "2024-02-01T00:00:00Z"
}
```

## Error Responses

<ResponseField name="400" type="Bad Request">
  Invalid request parameters or malformed request body
</ResponseField>

<ResponseField name="403" type="Forbidden">
  User does not have permission to perform the operation
</ResponseField>

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

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

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