Pull Requests API

Create, list, update, merge, and manage pull requests in your Gitea repositories

Overview

The Pull Requests API enables you to manage pull requests in your repositories. You can create PRs, list them with various filters, update their properties, merge them, and check merge status.

Pull Request Object

The PullRequest object represents a pull request with the following structure:

id · integer

The unique identifier of the pull request

number · integer

The pull request number (index) in the repository

title · string

The title of the pull request

body · string

The description body content of the pull request

state · string · default: "open"

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

draft · boolean

Whether the pull request is a draft (work in progress)

user · object

The user who created the pull request

base · object

Information about the target (base) branch

head · object

Information about the source (head) branch

merge_base · string

The commit SHA of the merge base

mergeable · boolean

Whether the pull request can be merged

merged · boolean

Whether the pull request has been merged

merged_at · string

Timestamp when the PR was merged (RFC 3339 format)

merged_by · object

The user who merged the pull request

allow_maintainer_edit · boolean

Whether maintainers can edit the pull request

labels · array

Array of label objects attached to the pull request

assignees · array

Array of user objects assigned to review the pull request

requested_reviewers · array

Array of user objects requested to review the pull request

comments · integer

The number of comments on the pull request

review_comments · integer

The number of review comments on the pull request diff

additions · integer

The number of lines added in the pull request

deletions · integer

The number of lines deleted in the pull request

changed_files · integer

The number of files changed in the pull request

Operations

List Pull Requests

List Repository Pull Requests

List all pull requests in a specific repository.

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

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

Query Parameters

state · string · default: "open"

Filter by pull request state. Options: open, closed, all

base_branch · string

Filter by target base branch of the pull request

sort · string

Sort order. Options: oldest, recentupdate, recentclose, leastupdate, mostcomment, leastcomment, priority

milestone · integer

Filter by milestone ID

labels · array

Array of label IDs to filter by

poster · string

Filter by pull request author 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/pulls?state=open&base_branch=main" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response

[
  {
    "id": 456,
    "number": 12,
    "title": "Add new feature",
    "body": "This PR implements the new authentication feature",
    "state": "open",
    "draft": false,
    "user": {
      "id": 2,
      "login": "developer"
    },
    "base": {
      "label": "myorg:main",
      "ref": "main",
      "sha": "abc123",
      "repo_id": 10
    },
    "head": {
      "label": "developer:feature-auth",
      "ref": "feature-auth",
      "sha": "def456",
      "repo_id": 11
    },
    "mergeable": true,
    "merged": false,
    "comments": 5,
    "review_comments": 3,
    "additions": 150,
    "deletions": 45,
    "changed_files": 8,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-16T14:30:00Z"
  }
]

Get Pull Request

Get a Single Pull Request

Retrieve details of a specific pull request by its index number.

Endpoint: GET /api/v1/repos/{owner}/{repo}/pulls/{index}

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the pull request

Example Request

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

Response

{
  "id": 456,
  "number": 12,
  "title": "Add new feature",
  "body": "This PR implements the new authentication feature",
  "state": "open",
  "base": {
    "label": "myorg:main",
    "ref": "main",
    "sha": "abc123"
  },
  "head": {
    "label": "developer:feature-auth",
    "ref": "feature-auth",
    "sha": "def456"
  },
  "mergeable": true,
  "merged": false
}

Create Pull Request

Create a Pull Request

Create a new pull request in a repository.

Endpoint: POST /api/v1/repos/{owner}/{repo}/pulls

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

head · string · required

The head branch. Can be a branch name or username:branch for forks

base · string · required

The base (target) branch

body · string

The description body content of the pull request

assignees · array

Array of usernames to assign to the pull request

labels · array

Array of label IDs to attach to the pull request

milestone · integer

Milestone ID to associate with the pull request

reviewers · array

Array of reviewer usernames

team_reviewers · array

Array of team names for review

allow_maintainer_edit · boolean

Whether to allow maintainers to edit the pull request

due_date · string

Deadline for the pull request (RFC 3339 format)

Example Request

curl -X POST "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user dashboard",
    "head": "feature-dashboard",
    "base": "main",
    "body": "This PR adds a user dashboard with analytics",
    "labels": [1, 3],
    "assignees": ["johndoe"],
    "reviewers": ["reviewer1", "reviewer2"]
  }'

Response (201 Created)

{
  "id": 457,
  "number": 13,
  "title": "Implement user dashboard",
  "body": "This PR adds a user dashboard with analytics",
  "state": "open",
  "user": {
    "id": 1,
    "login": "admin"
  },
  "base": {
    "label": "myorg:main",
    "ref": "main"
  },
  "head": {
    "label": "myorg:feature-dashboard",
    "ref": "feature-dashboard"
  },
  "mergeable": true,
  "merged": false,
  "created_at": "2024-01-17T09:00:00Z"
}

Update Pull Request

Update a Pull Request

Modify an existing pull request. If using a deadline, only the date will be taken into account.

Endpoint: PATCH /api/v1/repos/{owner}/{repo}/pulls/{index}

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the pull request to update

Request Body

title · string

New title for the pull request

body · string

New description body content

state · string

New state for the pull request. Options: open, closed

base · string

Change the target base branch

assignees · array

New array of assignee usernames (replaces existing)

labels · array

New array of label IDs (replaces existing)

milestone · integer

New milestone ID

allow_maintainer_edit · boolean

Update whether maintainers can edit the pull request

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/pulls/13" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement user analytics dashboard",
    "body": "Updated: This PR adds a comprehensive user dashboard"
  }'

Response (201 Created)

{
  "id": 457,
  "number": 13,
  "title": "Implement user analytics dashboard",
  "body": "Updated: This PR adds a comprehensive user dashboard",
  "state": "open",
  "updated_at": "2024-01-20T11:30:00Z"
}

Merge Pull Request

Merge a Pull Request

Merge a pull request into the base branch.

Endpoint: POST /api/v1/repos/{owner}/{repo}/pulls/{index}/merge

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the pull request to merge

Request Body

Do · string · default: "merge"

Merge method. Options: merge, rebase, rebase-merge, squash, manually-merged

MergeTitleField · string

Custom merge commit title

MergeMessageField · string

Custom merge commit message

delete_branch_after_merge · boolean

Whether to delete the head branch after merge

force_merge · boolean

Force merge even if checks haven’t passed

merge_when_checks_succeed · boolean

Schedule auto-merge when checks succeed

head_commit_id · string

HEAD commit SHA for verification

Example Request

curl -X POST "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls/13/merge" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Do": "squash",
    "MergeTitleField": "Add user analytics dashboard",
    "delete_branch_after_merge": true
  }'

Response (200 OK)

No response body is returned on successful merge.

Additional Operations

Check Merge Status

Check if a pull request has been merged.

Endpoint: GET /api/v1/repos/{owner}/{repo}/pulls/{index}/merge

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the pull request

Example Request

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

Response

• 204 No Content - Pull request has been merged
• 404 Not Found - Pull request has not been merged

Update Pull Request Branch

Merge the base branch into the head branch to update the pull request.

Endpoint: POST /api/v1/repos/{owner}/{repo}/pulls/{index}/update

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the pull request

Query Parameters

style · string

How to update the pull request. Options: merge, rebase

Example Request

curl -X POST "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls/13/update?style=rebase" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response (200 OK)

No response body is returned on success.

Cancel Auto-Merge

Cancel a scheduled auto-merge for a pull request.

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

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

index · integer · required

Index number of the pull request

Example Request

curl -X DELETE "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls/13/merge" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Response (204 No Content)

No response body is returned on success.

Get Pull Request by Base and Head

Get a pull request by specifying base and head branches.

Endpoint: GET /api/v1/repos/{owner}/{repo}/pulls/{base}/{head}

Path Parameters

owner · string · required

Owner of the repository

repo · string · required

Name of the repository

base · string · required

Base branch name

head · string · required

Head branch. Format: branch or username:branch for forks

Example Request

curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls/main/feature-auth" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Get Pull Request Commits

Get all commits for a pull request.

Endpoint: GET /api/v1/repos/{owner}/{repo}/pulls/{index}/commits

Query Parameters

page · integer · default: "1"

Page number for pagination

limit · integer

Number of items per page

verification · boolean · default: "true"

Include verification for every commit

files · boolean · default: "true"

Include list of affected files for every commit

Example Request

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

Get Pull Request Files

Get all changed files in a pull request.

Endpoint: GET /api/v1/repos/{owner}/{repo}/pulls/{index}/files

Query Parameters

skip-to · string

Skip to given file

whitespace · string

Whitespace behavior. Options: ignore-all, ignore-change, ignore-eol, show-all

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/pulls/13/files" \
  -H "Authorization: token YOUR_ACCESS_TOKEN"

Download Diff or Patch

Download the diff or patch file for a pull request.

Endpoint: GET /api/v1/repos/{owner}/{repo}/pulls/{index}.{diffType}

Path Parameters

diffType · string · required

Output format. Options: diff, patch

Query Parameters

binary · boolean

Whether to include binary file changes

Example Request

curl -X GET "https://gitea.example.com/api/v1/repos/myorg/myrepo/pulls/13.diff" \
  -H "Authorization: token YOUR_ACCESS_TOKEN" \
  -o pr-13.diff

Error Responses

403 · Forbidden

User does not have permission to perform the operation

404 · Not Found

Repository or pull request not found

405 · Method Not Allowed

Operation not allowed (e.g., cannot merge a work-in-progress PR)

409 · Conflict

Merge conflict or duplicate pull request

422 · Unprocessable Entity

Validation error (e.g., invalid base/head branches)

423 · Locked

Repository is archived and cannot be modified