Select an exact Draft version or return to automatic versioning
Checks your version choice against the required version bump, then regenerates the existing Draft pull request.
Send the Draft's ETag in If-Match to reject an intervening change with 412 precondition_failed before saving or regenerating. Omitting If-Match applies the selection to the current Draft. version_next is required; null restores automatic selection.
A 502 response means the selected version was saved, but regeneration failed. Follow the error's retryable and suggested_action fields. Repeating an unfinished selection resumes generation; repeating a completed selection starts no new work. If using If-Match, retrieve the Draft and confirm the saved selection before retrying with its current ETag.
A 409 draft_merged means the Draft merged; retrieve the Target and select a version on its draft_id. A 409 target_busy means the Target is publishing; wait and retry. A 409 version_occupied means the version is already released; retrieve the Draft and releases, choose a new version, and retry.
See conditional writes for ETag and If-Match.
Authorization
apiKey Organization API key from the console (ak_...), or an OAuth access token with user:org:read, the organization selected during consent, and the capability required by the operation.
In: header
Path Parameters
Unique identifier for a Draft.
^drf_[a-z0-9]{16}$Header Parameters
ETag from a preceding response. The write applies only if the resource still has that version; otherwise it returns 412 precondition_failed without changes. Omit to write the current version. See https://typeship.dev/docs/typeship-api#conditional-writes.
1 <= length <= 1024Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/drafts/drf_3q7m1v8k2p5d9h4c" \ -H "Content-Type: application/json" \ -d '{ "version_next": "1.1.0" }'{ "id": "drf_3q7m1v8k2p5d9h4c", "object": "draft", "target_id": "tgt_5m8q2v7k1p9d4h6c", "project_id": "prj_4k8m2v7q1p9d5h6c", "status": "working", "version_next": "1.1.0", "version_source": "api", "readiness": { "status": "pending", "description": "Checking the selected version.", "compatibility_api": "compatible", "compatibility_package": "compatible", "version_correct": null, "bump_required": "minor", "version_previous": "1.0.0", "title_error": null }, "changes": { "changelog": "Add shipment tracking.", "breaking_count": 0, "version_previous": "1.0.0" }, "head_sha": "0123456789abcdef0123456789abcdef01234567", "pull_request": { "url": "https://github.com/parcel-example/parcel-client/pull/12", "number": 12 }, "generation_id": "gen_7h2p5d9c3m8w1k6q", "conflicts": null, "customized_files": 2, "release_id": null, "created_at": "2026-09-23T08:00:00Z", "updated_at": "2026-09-23T08:30:00Z", "history_recovery": null, "request_id": "req_3k8m1v6q9p2d7h4c", "checks": []}Get a Draft GET
Returns the Draft's status. An open Draft also reports its typed reason when action is required, next version and its source, readiness, checks, and conflict counts. The response carries an `ETag`; send it in `If-Match` when updating the Draft to avoid changing a newer version selection.
List customized and conflicted files on a Draft GET
Lists the Draft's files that differ from the last merged package or need a conflict decision, ordered by path, without file content. Each conflict names its kind, the saved decision, and the sides you can read with getFile. With `filter=history`, lists files affected by a default-branch history rewrite; the list is empty when none is pending. Returns `409 resource_changed` while Typeship is carrying the Draft's latest commit forward (status working), or when the Draft changes between pages.