Branches

Workstreams are branches; “Live” is the main branch

A workstream, seen from the API, is a branch (BranchesEndpoint). Creating one forks from a source branch:

client.branches.create({ siteId, name: "redesign-hero", sourceBranchId: mainBranchId });

When you’re editing on a non-main branch, the editor’s toolbar doesn’t show a plain “Publish” button; it shows “Review and Publish,” which opens a merge review comparing your branch against main. Getting a workstream’s changes live is a merge, not a publish:

await client.merge.checkMergeability(siteId, sourceBranchId, targetBranchId);
await client.merge.preview(siteId, sourceBranchId, targetBranchId, {
  includeContent: true,        // include the actual content diff, not just a change count
  excludePathPrefixes: ["/_registry"],  // e.g. skip template-registry paths
});
await client.merge.execute(siteId, { sourceBranchId, targetBranchId });

WordPress equivalent: closest is a staging site you’d later sync to production, except P1’s version is a real branch/merge operation, not a plugin-driven file/DB copy. Drupal equivalent: closest is a content moderation workflow, but again, P1’s is a true branch fork + merge rather than a state field on each node.

Merge requests: a real review step, closer to a GitHub PR than either CMS

Beyond the direct check/preview/execute flow above, MergeEndpoint also supports a full merge-request lifecycle. The closest analog either platform’s developers will recognize is a pull request, not anything native to WordPress or Drupal:

const mr = await client.merge.createRequest(siteId, { sourceBranchId, targetBranchId });
await client.merge.listRequests(siteId, { status: "open" });
await client.merge.getRequest(siteId, mr.id);
await client.merge.updateRequest(siteId, mr.id, { /* e.g. title, description */ });
await client.merge.executeRequest(siteId, mr.id);      // merges it
await client.merge.deleteRequest(siteId, mr.id);        // or discard it unmerged

Use this instead of a direct execute() call when a workstream’s changes should go through an explicit review/approval step before landing on main. The direct mergeability check/preview/execute trio above is for a merge you’re doing right now, with no separate approval step.