# Create a pull request

> Start a change.

<div class="g1t-endpoint"><span class="g1t-method" data-method="post">POST</span><code>/repos/{owner}/{name}/pulls</code></div>

Opens a draft pull request with its own fork of the repository and returns the fork's git remote. Clone it, commit your work there, push, record your session as you go, then call [`mark_pull_request_ready`](/reference/api/pull-requests/mark-pull-request-ready/). Give the issue it is for whenever there is one. If the change is already on a branch pushed to the repository, give that branch instead: no fork is made and the pull request is ready for review at once.

`title` defaults to the issue's title, and is required when there is no `issue`. Push to `git.remote` with your username and an access token as the password.

Send `branch` to open the pull request from a branch already pushed to the repository. No fork is made, `fork` is `null`, `git.remote` is the repository itself, and the pull request is `open` at once.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`pull_request`](/reference/mcp/#pull_request) with `action` `create`, and the same inputs
- **Scope:** An access token needs [`pull_requests:write`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `owner` | string | Yes | The workspace that owns the repository. |
| `name` | string | Yes | The repository's name. |

## Body parameters

Send a JSON object. Names are `snake_case`, as in responses; the `camelCase` spelling is accepted too.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `issue` | integer | No | The number of the issue this is for. |
| `title` | string | No | Defaults to the issue's title. Required when there is no issue. |
| `branch` | string | No | A branch already pushed to the repository that holds the change. Leave out to get a fork. |
| `body` | string | No | Markdown: what changed and why. Mainly for pull requests from a branch. |
| `agent` | string | No | A label for the agent doing the work, e.g. "claude-code". |

## Example request

```sh
curl -X POST https://api.g1t.sh/repos/flagon-io/hello/pulls \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "issue": 12,
    "agent": "claude-code"
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "pull": {
    "id": "pr_01m43smh3vexsr5pmp60qwv0vs",
    "repo_id": "rep_01m3m5q6p0e2qaw6mmjahk0qrr",
    "number": 14,
    "issue": 12,
    "title": "Greeting should name the caller",
    "body": null,
    "agent": "claude-code",
    "runtime": "external",
    "status": "draft",
    "fork": {
      "namespace": "pulls",
      "name": "pr_01m43smh3vexsr5pmp60qwv0vs"
    },
    "fork_repo_id": "rep_01m43smh5xd7aw2kq9tv0b4c8e",
    "branch": null,
    "head_commit": null,
    "merge_base": null,
    "merged_by": null,
    "merged_at": null,
    "superseded_by": null,
    "check_status": null,
    "files": [],
    "assignees": [],
    "reviewers": [],
    "author": {
      "id": "usr_01kkntcg1eeb98j62xjm7eh09p",
      "username": "syntaqx",
      "kind": "user",
      "verified": false,
      "workspaces": []
    },
    "created_at": "2026-10-01T18:20:02.117Z",
    "updated_at": "2026-10-01T18:20:02.117Z"
  },
  "git": {
    "remote": "https://g1t.sh/pulls/pr_01m43smh3vexsr5pmp60qwv0vs.git",
    "username": "syntaqx",
    "password": "your g1t access token"
  }
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 409 | `conflict` | The request conflicts with the current state. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |