Compare source with target

All members. Direction matters. Uses every best common ancestor. Preview is immutable and expires after 24 hours. No automatic text merging.

POST /api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons

Operation: compareBranches · Download OpenAPI

Access

This operation does not use the panel session as its authentication mechanism. Follow the operation-specific checks described above.

session

{
  "type": "apiKey",
  "in": "cookie",
  "name": "__Host-localisync-session"
}

Parameters

Name	Location	Required	Description
workspaceId	path	Yes	See constraints below.
projectId	path	Yes	See constraints below.
Origin	header	Yes	See constraints below.
X-CSRF-Token	header	Yes	See constraints below.
Idempotency-Key	header	Yes	See constraints below.

workspaceId

{
  "type": "string",
  "format": "uuid"
}

projectId

{
  "type": "string",
  "format": "uuid"
}

Origin

{
  "type": "string",
  "format": "uri"
}

X-CSRF-Token

{
  "type": "string"
}

Idempotency-Key

{
  "type": "string",
  "format": "uuid"
}

Request body

Required: Yes.

application/json

Schema reference: Compare.

Field	Type	Required	Constraints / description
sourceId	string	Yes	format: "uuid"
targetId	string	Yes	format: "uuid"

{
  "$ref": "#/components/schemas/Compare"
}

Responses

202

Operation queued; poll its state.

Response headers:

{
  "Cache-Control": {
    "schema": {
      "type": "string",
      "const": "no-store"
    }
  }
}

Content type: application/json Schema reference: BranchJob.

Field	Type	Required	Constraints / description
id	string	Yes	format: "uuid"
workspaceId	string	Yes	format: "uuid"
projectId	string	Yes	format: "uuid"
kind	fork, compare, merge, delete	Yes	—
state	queued, processing, ready, completed, failed, conflict, cancelled, expired	Yes	—
version	integer	Yes	minimum: 1; maximum: 2147483646
summary	object	Yes	—
resultBranchId	See schema	Yes	—
appliedJobId	See schema	Yes	—
errorCode	See schema	Yes	—
createdAt	string	Yes	format: "date-time"
expiresAt	string	Yes	format: "date-time"
sourceBranchId	See schema	Yes	—
targetBranchId	See schema	Yes	—
actorId	string	Yes	format: "uuid"

{
  "$ref": "#/components/schemas/BranchJob"
}

400

Invalid request.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

401

Sign in required.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

403

Insufficient current workspace role.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

404

Resource unavailable in this scope.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

409

Version conflict, stale preview or content invariant.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

429

Request limit exceeded.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

503

Service unavailable; success is not implied.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	unauthorized, forbidden, invalid_request, not_found, conflict, rate_limited, unavailable	Yes	—
message	string	Yes	—
requestId	string	No	—
details	object	No	—

{
  "$ref": "#/components/schemas/Error"
}

Related guidance

Request errors and safe retries · Troubleshooting