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:

id · integer

The unique identifier of the issue

number · integer

The issue number (index) in the repository

title · string

The title of the issue

body · string

The description body content of the issue

state · string · default: "open"

The current state of the issue. Possible values: open, closed

user · object

The user who created the issue

labels · array

Array of label objects attached to the issue

assignees · array

Array of user objects assigned to the issue

milestone · object

The milestone associated with the issue

comments · integer

The number of comments on the issue

created_at · string

Timestamp when the issue was created (RFC 3339 format)

updated_at · string

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

closed_at · string

Timestamp when the issue was closed (RFC 3339 format)

due_date · string

The deadline for the issue (RFC 3339 format)

Operations

List Issues

List Repository Issues

List all issues in a specific repository.

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

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

Query Parameters

state · string · default: "open"

Filter by issue state. Options: open, closed, all

labels · string

Comma-separated list of label names to filter by

milestones · string

Comma-separated list of milestone names or IDs to filter by

q · string

Search query string

type · string

Filter by type. Options: issues, pulls

since · string

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

before · string

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

created_by · string

Filter by creator username

assigned_by · string

Filter by assignee username

mentioned_by · string

Filter by mentioned username

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?state=open&labels=bug,enhancement" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

[
  {
    "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
  }
]

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

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the issue

Example Request

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

Response

{
  "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"
}

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

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

Request Body

title · string · required

The title of the issue

body · string

The description body content of the issue

ref · string

Reference to a branch or commit

assignees · array

Array of usernames to assign to the issue

labels · array

Array of label IDs to attach to the issue

milestone · integer

Milestone ID to associate with the issue

due_date · string

Deadline for the issue (RFC 3339 format)

closed · boolean · default: "false"

Whether to create the issue in closed state

Example Request

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)

{
  "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"
}

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

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the issue to update

Request Body

title · string

New title for the issue

body · string

New description body content

state · string

New state for the issue. Options: open, closed

assignees · array

New array of assignee usernames (replaces existing assignees)

milestone · integer

New milestone ID (use 0 to remove milestone)

due_date · string

New deadline (RFC 3339 format)

unset_due_date · boolean

Set to true to remove the deadline

Example Request

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)

{
  "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"
}

Delete Issue

Delete an Issue

Permanently delete an issue from a repository.

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

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the issue to delete

Example Request

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.

Search Issues

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

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

Query Parameters

state · string · default: "open"

State of the issue. Options: open, closed, all

labels · string

Comma-separated list of label names

milestones · string

Comma-separated list of milestone names

q · string

Search query string

type · string

Filter by type. Options: issues, pulls

owner · string

Filter by repository owner

created_by · string

Filter by creator username

assigned · boolean

Filter issues assigned to the authenticated user

created · boolean

Filter issues created by the authenticated user

mentioned · boolean

Filter issues mentioning the authenticated user

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/issues/search?q=authentication&state=open&assigned=true" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

[
  {
    "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

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the issue

Request Body

due_date · string · required

The new deadline (RFC 3339 format) or null to remove

Example Request

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)

{
  "due_date": "2024-02-01T00:00:00Z"
}

Error Responses

400 · Bad Request

Invalid request parameters or malformed request body

403 · Forbidden

User does not have permission to perform the operation

404 · Not Found

Repository or issue not found

422 · Unprocessable Entity

Validation error (e.g., missing required fields)

423 · Locked

Repository is archived and cannot be modified