Read one durable Merge command

GET

/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: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --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>'

Requires wamp.cloud.sessions:read. The safe way to learn a merge’s fate after a lost response — never re-issue a PUT to find out. succeeded carries mergedCommitSha; waiting means a when_ready command is parked and will be retried, with lastError.code naming what it is waiting on (typically merge_not_ready for a failing check or an unsatisfied review); failed is terminal and never retried, and attempts counts provider attempts rather than agent work. A merge id belonging to a different Session or Publication is 404.

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

Responses

200

Merge

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"
  }
}

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"
}