---
title: "Create a new patch."
method: POST
path: "/apps/{appId}/patches"
tags: ["patches"]
---

# Create a new patch.

`POST /apps/{appId}/patches`

## Request

- Base URL: `https://api.shorebird.dev/api/v1`
- URL: `https://api.shorebird.dev/api/v1/apps/{appId}/patches`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

## Request body

- CreatePatchRequest: The request body for POST /apps/{appId}/patches.
  - `release_id` integer, required: The ID of the release.
  - `metadata` object, required: Additional information about the command that was run to create the patch and the environment it was run in.

## Response `201`

The newly-created patch.

- CreatePatchResponse: The response body for POST /apps/{appId}/patches. Deliberately narrower than [Patch]: a freshly-created patch has no `notes` yet (those are set via PATCH /.../{patchId}), so this endpoint exposes only the identifiers the client needs to upload artifacts.
  - `id` integer, required: The unique patch identifier.
  - `number` integer, required: The patch number. A larger number equates to a newer patch.

## Other responses

- `default`: Standard error response. Emitted for any non-2xx status where a body can be decoded into an [ErrorResponse].

## Changes

- **2026-11-05** `941da8871d10`: 1 info
  - added the optional property `documentation_url` to the response with the `default` status

[Operation history](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/changes/apps/:appId/patches/post.md)

---

[API](https://skmtc.dev/shorebird/apis/shorebird-codepush-api.md) - [All operations](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shorebird/apis/shorebird-codepush-api/revisions/941da8871d10?raw)