Publish one exact reviewed revision as a pull request

PUT

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

const url = 'https://example.com/v1/sessions/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731/publications/9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"revision":"88b7d76865ac445123d1adb83bf4e8e039e16bc02c5c675725a62a849f514441","title":"Rate limit the payments endpoint","body":"Adds a sliding-window limiter of 100 requests per minute per API key on POST /charges.\n\nCloses PAY-4821.","draft":true}'
};

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 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "revision": "88b7d76865ac445123d1adb83bf4e8e039e16bc02c5c675725a62a849f514441", "title": "Rate limit the payments endpoint", "body": "Adds a sliding-window limiter of 100 requests per minute per API key on POST /charges.\n\nCloses PAY-4821.", "draft": true }'

The caller-owned Publication id is the recovery unit. A retry never adopts a live remote head or rebuilds a different commit.

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

Request Body^required

application/json

Body of the idempotent publish command. The caller-owned Publication id is the recovery unit: a retry re-addresses the same command and never adopts a live remote head or rebuilds a different commit.

object

revision

required

The exact review revision to publish; if the sandbox has changed since that review the command is refused rather than quietly rebuilt

string

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

title

required

Single-line pull-request title

string

>= 1 characters <= 256 characters

body

required

Pull-request description in markdown; may be empty

string

<= 65536 characters

draft

Whether to open the pull request as a draft, which is the default

boolean

default: true

Example

{
  "revision": "88b7d76865ac445123d1adb83bf4e8e039e16bc02c5c675725a62a849f514441",
  "title": "Rate limit the payments endpoint",
  "body": "Adds a sliding-window limiter of 100 requests per minute per API key on POST /charges.\n\nCloses PAY-4821.",
  "draft": true
}

Responses

200

Idempotent replay

application/json

Envelope returned when a Publication is created or read.

object

publication

required

The Publication 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 Publication id, which is also the retry and recovery unit

string format: uuid

sessionId

required

Session whose reviewed changes are being published

string format: uuid

status

required

admitted on acceptance, prepared once the local commit exists, attempted while the provider write is in flight, then terminal succeeded or failed

string

Allowed values: admitted prepared attempted succeeded failed

revision

required

The review revision this Publication is permanently pinned to

string

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

title

required

Pull-request title as submitted

string

result

Present once status is succeeded — the WAMP-owned branch, the exact commit pushed, and the pull request, where reused means an existing open pull request was recovered instead of a new one being opened

object

branch

required

string

commitSha

required

Lowercase hex 40-character Git object id naming an exact commit or tree in the source repository.

string

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

pullRequest

required

object

number

required

integer

url

required

string format: uri

draft

required

boolean

reused

required

boolean

lastError

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

object

code

string

createdAt

required

When the Publication was admitted

string format: date-time

updatedAt

required

Last durable state change of the command

string format: date-time

completedAt

When the Publication reached succeeded or failed

string format: date-time

Example

{
  "publication": {
    "id": "1e8d4b62-7f05-4c3a-9d21-6a48f0b7c952",
    "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "status": "succeeded",
    "revision": "88b7d76865ac445123d1adb83bf4e8e039e16bc02c5c675725a62a849f514441",
    "title": "Rate limit the payments endpoint",
    "result": {
      "branch": "wamp/publications-v1/cloud-9f2b7c14-59d3-4f7a-b8e1-2a6c05-d8af1a5a",
      "commitSha": "281c35bbe1f0ed047127957c11858d1394722abf",
      "pullRequest": {
        "number": 482,
        "url": "https://github.com/acme/checkout-service/pull/482",
        "draft": true,
        "reused": false
      }
    },
    "createdAt": "2026-08-12T09:52:31Z",
    "updatedAt": "2026-08-12T09:52:39Z",
    "completedAt": "2026-08-12T09:52:39Z"
  }
}

201

Publication admitted

application/json

Envelope returned when a Publication is created or read.

object

publication

required

The Publication 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 Publication id, which is also the retry and recovery unit

string format: uuid

sessionId

required

Session whose reviewed changes are being published

string format: uuid

status

required

admitted on acceptance, prepared once the local commit exists, attempted while the provider write is in flight, then terminal succeeded or failed

string

Allowed values: admitted prepared attempted succeeded failed

revision

required

The review revision this Publication is permanently pinned to

string

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

title

required

Pull-request title as submitted

string

result

object

branch

required

string

commitSha

required

Lowercase hex 40-character Git object id naming an exact commit or tree in the source repository.

string

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

pullRequest

required

object

number

required

integer

url

required

string format: uri

draft

required

boolean

reused

required

boolean

lastError

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

object

code

string

createdAt

required

When the Publication was admitted

string format: date-time

updatedAt

required

Last durable state change of the command

string format: date-time

completedAt

When the Publication reached succeeded or failed

string format: date-time

Example

{
  "publication": {
    "id": "1e8d4b62-7f05-4c3a-9d21-6a48f0b7c952",
    "sessionId": "9f2b7c14-59d3-4f7a-b8e1-2a6c05d4e731",
    "status": "succeeded",
    "revision": "88b7d76865ac445123d1adb83bf4e8e039e16bc02c5c675725a62a849f514441",
    "title": "Rate limit the payments endpoint",
    "result": {
      "branch": "wamp/publications-v1/cloud-9f2b7c14-59d3-4f7a-b8e1-2a6c05-d8af1a5a",
      "commitSha": "281c35bbe1f0ed047127957c11858d1394722abf",
      "pullRequest": {
        "number": 482,
        "url": "https://github.com/acme/checkout-service/pull/482",
        "draft": true,
        "reused": false
      }
    },
    "createdAt": "2026-08-12T09:52:31Z",
    "updatedAt": "2026-08-12T09:52:39Z",
    "completedAt": "2026-08-12T09:52:39Z"
  }
}

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

Publish one exact reviewed revision as a pull request

Authorizations

Parameters

Path Parameters

Example

Example

Request Bodyrequired

Example

Responses

200

Example

201

Example

Headers

404

Example

409

Example

Request Body^required