Merge the exact successful Publication head

PUT

/v1/sessions/{sessionId}/publications/{publicationId}/merges/{mergeId}

const url = 'https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/publications/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/merges/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"strategy":"squash","mode":"when_ready","commitTitle":"Rate limit the payments endpoint (#482)","commitMessage":"Adds a sliding-window limiter of 100 requests per minute per API key."}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PUT \
  --url https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/publications/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/merges/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "strategy": "squash", "mode": "when_ready", "commitTitle": "Rate limit the payments endpoint (#482)", "commitMessage": "Adds a sliding-window limiter of 100 requests per minute per API key." }'

Branch protection stays authoritative. mode=when_ready leaves a durable waiting command; mode=now fails definitively when the provider is not mergeable.

Authorizations

cloudInstallationBearer

Parameters

Path Parameters

sessionId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

A UUID you mint and own; it is the idempotency key for creation and the address of every Turn, artifact and publication underneath

publicationId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

A UUID you mint for this publish attempt; it is the idempotency and recovery key for the pull request

mergeId

required

A UUID identifying one Cloud resource; Session, Turn, Publication and Merge ids are minted by the caller so an ambiguous retry addresses the same durable command instead of creating a second one.

string format: uuid

Example

9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731

A UUID you mint for this merge command; it is the idempotency and recovery key

Request Body^required

application/json

Body of the idempotent merge command. Every field has a default, so an empty object requests a squash merge attempted immediately.

object

strategy

Provider merge strategy — squash by default, or merge or rebase when the repository allows it

string

default: squash

Allowed values: merge squash rebase

mode

now fails definitively when the provider reports the pull request is not mergeable; when_ready parks a durable command that waits for checks and branch protection

string

default: now

Allowed values: now when_ready

commitTitle

Overrides the merge commit title the provider would otherwise generate

string

>= 1 characters <= 256 characters

commitMessage

Overrides the merge commit body the provider would otherwise generate

string

<= 65536 characters

Example

{
  "strategy": "squash",
  "mode": "when_ready",
  "commitTitle": "Rate limit the payments endpoint (#482)",
  "commitMessage": "Adds a sliding-window limiter of 100 requests per minute per API key."
}

Responses

200

Idempotent replay

application/json

Envelope returned when a Merge is created or read.

object

merge

required

The Merge as it stands after this request; a 201 means it was newly admitted and a 200 means an identical retry returned the stored command

object

required

The caller-owned Merge id, a separate recovery unit from the Publication it integrates

string format: uuid

sessionId

required

Session the merged work belongs to

string format: uuid

publicationId

required

Publication whose successful head this command merges

string format: uuid

status

required

admitted on acceptance, attempted while the provider merge is in flight, waiting for a when_ready command parked until the pull request becomes mergeable, then terminal succeeded or failed

string

Allowed values: admitted attempted waiting succeeded failed

strategy

required

Merge strategy actually recorded for this command

string

Allowed values: merge squash rebase

mode

required

Whether this command was admitted as an immediate merge or a durable wait

string

Allowed values: now when_ready

pullRequestNumber

required

Pull request being merged, taken from the Publication result rather than from the caller

integer

expectedHeadSha

required

The exact head this merge is pinned to; if the pull-request head moves the command fails instead of integrating unreviewed commits

string

/^[a-f0-9]{40}$/

mergedCommitSha

Commit the provider created on the base branch; present once status is succeeded

string

/^[a-f0-9]{40}$/

lastError

Coarse machine code for the failure; present when status is failed

object

code

string

attempts

required

How many times a worker has attempted the provider merge, including waits that were re-checked

integer

createdAt

required

When the Merge was admitted

string format: date-time

updatedAt

required

Last durable state change of the command

string format: date-time

completedAt

When the Merge reached succeeded or failed

string format: date-time

Example

{
  "merge": {
    "id": "5a3c9f71-2b84-4e6d-8c07-9f1b3d52e480",
    "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "publicationId": "1e8d4b62-7f05-4c3a-9d21-6a48f0b7c952",
    "status": "succeeded",
    "strategy": "squash",
    "mode": "when_ready",
    "pullRequestNumber": 482,
    "expectedHeadSha": "281c35bbe1f0ed047127957c11858d1394722abf",
    "mergedCommitSha": "fb7f597cd47357afe2902c78ebd02c2b914b0e91",
    "attempts": 3,
    "createdAt": "2026-08-12T10:03:12Z",
    "updatedAt": "2026-08-12T10:12:47Z",
    "completedAt": "2026-08-12T10:12:47Z"
  }
}

201

Merge admitted

application/json

Envelope returned when a Merge is created or read.

object

merge

required

The Merge as it stands after this request; a 201 means it was newly admitted and a 200 means an identical retry returned the stored command

object

required

The caller-owned Merge id, a separate recovery unit from the Publication it integrates

string format: uuid

sessionId

required

Session the merged work belongs to

string format: uuid

publicationId

required

Publication whose successful head this command merges

string format: uuid

status

required

string

Allowed values: admitted attempted waiting succeeded failed

strategy

required

Merge strategy actually recorded for this command

string

Allowed values: merge squash rebase

mode

required

Whether this command was admitted as an immediate merge or a durable wait

string

Allowed values: now when_ready

pullRequestNumber

required

Pull request being merged, taken from the Publication result rather than from the caller

integer

expectedHeadSha

required

The exact head this merge is pinned to; if the pull-request head moves the command fails instead of integrating unreviewed commits

string

/^[a-f0-9]{40}$/

mergedCommitSha

Commit the provider created on the base branch; present once status is succeeded

string

/^[a-f0-9]{40}$/

lastError

Coarse machine code for the failure; present when status is failed

object

code

string

attempts

required

How many times a worker has attempted the provider merge, including waits that were re-checked

integer

createdAt

required

When the Merge was admitted

string format: date-time

updatedAt

required

Last durable state change of the command

string format: date-time

completedAt

When the Merge reached succeeded or failed

string format: date-time

Example

{
  "merge": {
    "id": "5a3c9f71-2b84-4e6d-8c07-9f1b3d52e480",
    "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "publicationId": "1e8d4b62-7f05-4c3a-9d21-6a48f0b7c952",
    "status": "waiting",
    "strategy": "squash",
    "mode": "when_ready",
    "pullRequestNumber": 482,
    "expectedHeadSha": "281c35bbe1f0ed047127957c11858d1394722abf",
    "lastError": {
      "code": "merge_not_ready"
    },
    "attempts": 1,
    "createdAt": "2026-08-12T10:03:12Z",
    "updatedAt": "2026-08-12T10:03:14Z"
  }
}

Headers

Location

string

404

The resource is missing or inaccessible

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_session_not_found"
}

409

Idempotency, lifecycle, revision or single-flight conflict

application/json

Failure body returned with every non-2xx JSON response; branch on the machine code, never on prose or on the HTTP status alone.

object

error

required

Stable machine code

string

requiredScope

The installation capability the presented credential lacks, returned with insufficient_scope so an integrator knows exactly which capability to request

string

retryAfterSeconds

Advisory seconds to wait before retrying; returned on rate-limit denials, where the Retry-After header carries the same value

integer

>= 1

key

additional properties

any

Example

{
  "error": "cloud_session_conflict"
}

Merge the exact successful Publication head

Authorizations

Parameters

Path Parameters

Example

Example

Example

Request Bodyrequired

Example

Responses

200

Example

201

Example

Headers

404

Example

409

Example

Request Body^required