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

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

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

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

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

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

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

<ResponseField name="draft" type="boolean">
  Whether the pull request is a draft (work in progress)
</ResponseField>

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

<ResponseField name="base" type="object">
  Information about the target (base) branch
</ResponseField>

<ResponseField name="head" type="object">
  Information about the source (head) branch
</ResponseField>

<ResponseField name="merge_base" type="string">
  The commit SHA of the merge base
</ResponseField>

<ResponseField name="mergeable" type="boolean">
  Whether the pull request can be merged
</ResponseField>

<ResponseField name="merged" type="boolean">
  Whether the pull request has been merged
</ResponseField>

<ResponseField name="merged_at" type="string">
  Timestamp when the PR was merged (RFC 3339 format)
</ResponseField>

<ResponseField name="merged_by" type="object">
  The user who merged the pull request
</ResponseField>

<ResponseField name="allow_maintainer_edit" type="boolean">
  Whether maintainers can edit the pull request
</ResponseField>

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

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

<ResponseField name="requested_reviewers" type="array">
  Array of user objects requested to review the pull request
</ResponseField>

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

<ResponseField name="review_comments" type="integer">
  The number of review comments on the pull request diff
</ResponseField>

<ResponseField name="additions" type="integer">
  The number of lines added in the pull request
</ResponseField>

<ResponseField name="deletions" type="integer">
  The number of lines deleted in the pull request
</ResponseField>

<ResponseField name="changed_files" type="integer">
  The number of files changed in the pull request
</ResponseField>

## Operations

<Tabs>
  <Tab title="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

    <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 pull request state. Options: `open`, `closed`, `all`
    </ParamField>

    <ParamField query="base_branch" type="string">
      Filter by target base branch of the pull request
    </ParamField>

    <ParamField query="sort" type="string">
      Sort order. Options: `oldest`, `recentupdate`, `recentclose`, `leastupdate`, `mostcomment`, `leastcomment`, `priority`
    </ParamField>

    <ParamField query="milestone" type="integer">
      Filter by milestone ID
    </ParamField>

    <ParamField query="labels" type="array">
      Array of label IDs to filter by
    </ParamField>

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

    #### Response

    ```json theme={null}
    [
      {
        "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"
      }
    ]
    ```
  </Tab>

  <Tab title="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

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

    #### Example Request

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

    #### Response

    ```json theme={null}
    {
      "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
    }
    ```
  </Tab>

  <Tab title="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

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

    <ParamField body="head" type="string" required>
      The head branch. Can be a branch name or `username:branch` for forks
    </ParamField>

    <ParamField body="base" type="string" required>
      The base (target) branch
    </ParamField>

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

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

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

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

    <ParamField body="reviewers" type="array">
      Array of reviewer usernames
    </ParamField>

    <ParamField body="team_reviewers" type="array">
      Array of team names for review
    </ParamField>

    <ParamField body="allow_maintainer_edit" type="boolean">
      Whether to allow maintainers to edit the pull request
    </ParamField>

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

    #### Example Request

    ```bash theme={null}
    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)

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="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

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

    #### Request Body

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

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

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

    <ParamField body="base" type="string">
      Change the target base branch
    </ParamField>

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

    <ParamField body="labels" type="array">
      New array of label IDs (replaces existing)
    </ParamField>

    <ParamField body="milestone" type="integer">
      New milestone ID
    </ParamField>

    <ParamField body="allow_maintainer_edit" type="boolean">
      Update whether maintainers can edit the pull request
    </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/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)

    ```json theme={null}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="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

    <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 pull request to merge
    </ParamField>

    #### Request Body

    <ParamField body="Do" type="string" default="merge">
      Merge method. Options: `merge`, `rebase`, `rebase-merge`, `squash`, `manually-merged`
    </ParamField>

    <ParamField body="MergeTitleField" type="string">
      Custom merge commit title
    </ParamField>

    <ParamField body="MergeMessageField" type="string">
      Custom merge commit message
    </ParamField>

    <ParamField body="delete_branch_after_merge" type="boolean">
      Whether to delete the head branch after merge
    </ParamField>

    <ParamField body="force_merge" type="boolean">
      Force merge even if checks haven't passed
    </ParamField>

    <ParamField body="merge_when_checks_succeed" type="boolean">
      Schedule auto-merge when checks succeed
    </ParamField>

    <ParamField body="head_commit_id" type="string">
      HEAD commit SHA for verification
    </ParamField>

    #### Example Request

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

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

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

#### Example Request

```bash theme={null}
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

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

#### Query Parameters

<ParamField query="style" type="string">
  How to update the pull request. Options: `merge`, `rebase`
</ParamField>

#### Example Request

```bash theme={null}
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

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

#### Example Request

```bash theme={null}
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

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

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

<ParamField path="base" type="string" required>
  Base branch name
</ParamField>

<ParamField path="head" type="string" required>
  Head branch. Format: `branch` or `username:branch` for forks
</ParamField>

#### Example Request

```bash theme={null}
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

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="limit" type="integer">
  Number of items per page
</ParamField>

<ParamField query="verification" type="boolean" default="true">
  Include verification for every commit
</ParamField>

<ParamField query="files" type="boolean" default="true">
  Include list of affected files for every commit
</ParamField>

#### Example Request

```bash theme={null}
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

<ParamField query="skip-to" type="string">
  Skip to given file
</ParamField>

<ParamField query="whitespace" type="string">
  Whitespace behavior. Options: `ignore-all`, `ignore-change`, `ignore-eol`, `show-all`
</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/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

<ParamField path="diffType" type="string" required>
  Output format. Options: `diff`, `patch`
</ParamField>

#### Query Parameters

<ParamField query="binary" type="boolean">
  Whether to include binary file changes
</ParamField>

#### Example Request

```bash theme={null}
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

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

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

<ResponseField name="405" type="Method Not Allowed">
  Operation not allowed (e.g., cannot merge a work-in-progress PR)
</ResponseField>

<ResponseField name="409" type="Conflict">
  Merge conflict or duplicate pull request
</ResponseField>

<ResponseField name="422" type="Unprocessable Entity">
  Validation error (e.g., invalid base/head branches)
</ResponseField>

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