Issues API - Gitea

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:

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
Get Issue
Create Issue
Update Issue
Delete Issue

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

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

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

Overview

Repositories

Issues & Pull Requests

Organizations & Teams

Users

Actions & Packages

​Overview

​Issue Object

​Operations

​List Repository Issues

​Path Parameters

​Query Parameters

​Example Request

​Response

​Get a Single Issue

​Path Parameters

​Example Request

​Response

​Create an Issue

​Path Parameters

​Request Body

​Example Request

​Response (201 Created)

​Update an Issue

​Path Parameters

​Request Body

​Example Request

​Response (201 Created)

​Delete an Issue

​Path Parameters

​Example Request

​Response (204 No Content)

​Search Issues

​Query Parameters

​Example Request

​Response

​Update Issue Deadline

​Path Parameters

​Request Body

​Example Request

​Response (201 Created)

​Error Responses

Build docs developers (and LLMs) love

Overview

Issue Object

Operations

List Repository Issues

Path Parameters

Query Parameters

Example Request

Response

Get a Single Issue

Path Parameters

Example Request

Response

Create an Issue

Path Parameters

Request Body

Example Request

Response (201 Created)

Update an Issue

Path Parameters

Request Body

Example Request

Response (201 Created)

Delete an Issue

Path Parameters

Example Request

Response (204 No Content)

Search Issues

Query Parameters

Example Request

Response

Update Issue Deadline

Path Parameters

Request Body

Example Request

Response (201 Created)

Error Responses