---
title: "Open a draft pull request for a post"
method: POST
path: "/v1/posts/{postId}/pull-request"
tags: ["Content"]
---

# Open a draft pull request for a post

`POST /v1/posts/{postId}/pull-request`

## Request

- Base URL: `https://api.usenotra.com`
- URL: `https://api.usenotra.com/v1/posts/{postId}/pull-request`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/usenotra/apis/notra-api/docs/v1/posts/:postId/pull-request/post.ts> (a function with typed inputs; its response is checked against the schema)

Exports a saved blog post or changelog to a draft GitHub pull request, using the repository's configured content path, site metadata and image handling, the same as the dashboard. Always opens a pull request, even for repositories set to publish directly, and never merges it. Calling it again for the same post and repository updates its open pull request instead of opening another.

## Path parameters

- `postId` string, required

## Request body

- object: Where to open the pull request. Omit both fields when the organization has exactly one connected GitHub repository.
  - `integrationId` string: GitHub integration ID from GET /v1/integrations to open the pull request in.
  - `github` object: Connected repository by owner and name, instead of integrationId.
    - `owner` string, required
    - `repo` string, required

## Response `200`

Draft pull request opened or updated

- object
  - `organization` object, required
    - `id` string, required
    - `slug` string, required
    - `name` string, required
    - `logo` string, nullable, required
  - `pullRequest` object, required
    - `number` integer, required
    - `url` string, uri, required
    - `branchName` string, required
    - `path` string, required: Repository path of the post file on the branch.
    - `operation` 'created' | 'updated', required: created for a new draft pull request, updated when the post's open pull request was refreshed instead.

## Other responses

- `400`: Invalid request, no matching repository, or the post is not a blog post or changelog
- `401`: Missing or invalid API key
- `403`: Forbidden
- `404`: Post or organization not found
- `429`: Rate limit exceeded. This endpoint allows 60 requests per 1 minute per API key.
- `502`: GitHub could not prepare the pull request
- `503`: Pull request export is unavailable or GitHub publishing is rate limited
- `504`: The export timed out and may still complete

## Changes

- **2026-11-08** `d4107f0fec1f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/usenotra/apis/notra-api/changes/v1/posts/:postId/pull-request/post.md)

---

[API](https://skmtc.dev/usenotra/apis/notra-api.md) - [All operations](https://skmtc.dev/usenotra/apis/notra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usenotra/apis/notra-api/revisions/a81c93229b54?raw)