Pull Requests API

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:

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
Get Pull Request
Create Pull Request
Update Pull Request
Merge Pull Request

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

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

Documentation Index

​Overview

​Pull Request Object

​Operations

​List Repository Pull Requests

​Path Parameters

​Query Parameters

​Example Request

​Response

​Get a Single Pull Request

​Path Parameters

​Example Request

​Response

​Create a Pull Request

​Path Parameters

​Request Body

​Example Request

​Response (201 Created)

​Update a Pull Request

​Path Parameters

​Request Body

​Example Request

​Response (201 Created)

​Merge a Pull Request

​Path Parameters

​Request Body

​Example Request

​Response (200 OK)

​Additional Operations

​Check Merge Status

​Path Parameters

​Example Request

​Response

​Update Pull Request Branch

​Path Parameters

​Query Parameters

​Example Request

​Response (200 OK)

​Cancel Auto-Merge

​Path Parameters

​Example Request

​Response (204 No Content)

​Get Pull Request by Base and Head

​Path Parameters

​Example Request

​Get Pull Request Commits

​Query Parameters

​Example Request

​Get Pull Request Files

​Query Parameters

​Example Request

​Download Diff or Patch

​Path Parameters

​Query Parameters

​Example Request

​Error Responses

Overview

Pull Request Object

Operations

List Repository Pull Requests

Path Parameters

Query Parameters

Example Request

Response

Get a Single Pull Request

Path Parameters

Example Request

Response

Create a Pull Request

Path Parameters

Request Body

Example Request

Response (201 Created)

Update a Pull Request

Path Parameters

Request Body

Example Request

Response (201 Created)

Merge a Pull Request

Path Parameters

Request Body

Example Request

Response (200 OK)

Additional Operations

Check Merge Status

Path Parameters

Example Request

Response

Update Pull Request Branch

Path Parameters

Query Parameters

Example Request

Response (200 OK)

Cancel Auto-Merge

Path Parameters

Example Request

Response (204 No Content)

Get Pull Request by Base and Head

Path Parameters

Example Request

Get Pull Request Commits

Query Parameters

Example Request

Get Pull Request Files

Query Parameters

Example Request

Download Diff or Patch

Path Parameters

Query Parameters

Example Request

Error Responses