Branches API
Internal Application API
These are internal SPA routes (cookie/session authenticated, used by the Studio app), not a versioned public contract — they may change between releases. For external integrations, use the Public API.
Content operations in Studio create cr/* feature branches. These branches can be reviewed and merged (in review workflow) or are auto-merged (in auto-merge workflow).
All branch endpoints are project-scoped:
/api/workspaces/:workspaceId/projects/:projectId/branches/...Git Architecture
Studio uses a two-branch strategy:
contentrain-- the SSOT (Single Source of Truth) branch for contentcr/*-- feature branches for individual operations (e.g.,cr/content/blog-post/en/1774800862-27c1)
The merge flow is: cr/* -> contentrain -> main
List Branches
List all pending cr/* content branches. Each row is resolved into the change it represents (model, locale, time) so clients do not have to parse the branch name.
GET /api/workspaces/:workspaceId/projects/:projectId/branchesAuth
Any project member.
Response
{
"sync": { "...": "content-sync state, or null if it could not be read" },
"branches": [
{
"name": "cr/content/blog-post/en/1774800862-27c1",
"sha": "abc123def456",
"protected": false,
"scope": "content",
"modelId": "blog-post",
"modelName": "Blog Post",
"locale": "en",
"timestamp": 1774800862,
"changesRequested": false
}
]
}modelId and modelName are set only for content and model scoped branches (otherwise null). changesRequested is true while a reviewer's change request is open on the branch. sync reports where the contentrain branch stands against the repository's own branch; it is null when the state cannot be read.
Get Branch Diff
Get what a branch changes, compared to the contentrain base branch. By default the response is a semantic review (entries, changed fields, status transitions) built from the project's models. Add ?raw=1 for the file-level diff.
GET /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/diffAny project member can read it. Only cr/* branches can be diffed (400 otherwise).
URL Encoding
Branch names contain / characters. Encode them in the URL:
/branches/cr%2Fcontent%2Fblog-post%2Fen%2F1774800862-27c1/diffResponse (default)
The semantic review of the branch, plus the caller's review state:
| Field | Description |
|---|---|
branch, info, groups, schema, settings, unclassified, summary | The review itself: changed entries and fields grouped by model and locale, schema and settings changes, files Studio could not classify, and added/updated/removed counts |
canMerge, canReject | Whether the caller may merge or reject the branch |
canRequestChanges | true if the caller may request changes |
changesRequested | { comment, requestedBy, requestedAt } while a change request is open, otherwise null |
approval | The approval-policy decision for this branch (allowed, risk, reasons, requirements, ...), or null when the project merges without approvals (or the decision could not be resolved) |
approvedBy | Recorded approvals: [{ approver, at, note }] |
Response (?raw=1)
{
"branch": "cr/content/blog-post/en/1774800862-27c1",
"files": [
{ "path": ".contentrain/content/blog/blog-post/en.json", "status": "modified" }
],
"contents": {
".contentrain/content/blog/blog-post/en.json": {
"before": { "a1b2c3d4e5f6": { "title": "Old Title" } },
"after": { "a1b2c3d4e5f6": { "title": "New Title" } }
}
}
}JSON files are returned parsed; before is null for an added file and after is null for a removed one.
Merge Branch
Merge a cr/* branch. Two-step process: merges into contentrain, then advances contentrain to main.
POST /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/mergeThe :branch segment is percent-encoded (see URL Encoding).
Response
{
"merged": true,
"sha": "abc123def456",
"pullRequestUrl": null
}Branch Protection
If the main branch has protection rules requiring pull requests, Studio creates a PR and attempts to merge it. The pullRequestUrl field contains the PR URL.
Auth
Requires reviewer, admin, or owner role (403 otherwise).
On a project that uses the review workflow, the role is not enough: the project's approval policy must also be satisfied by the approvals recorded for the branch (see Approve a Branch). On an auto-merge project no approval is asked for.
Errors
| Status | Condition |
|---|---|
400 | Not a cr/* branch |
403 | Caller cannot merge, or the approval policy is not satisfied. The latter returns data.approval with the policy decision (reasons, requirements) |
409 | The branch got a new commit after it was approved. The merge is pinned to the approved tip, so review the new changes first |
503 | The branch tip could not be read, so the pinned merge was not attempted. Retry shortly |
Approve a Branch
Record your decision on a pending branch. An approval covers one plan (the diff as reviewed) at one branch tip: pushing another commit invalidates it.
POST /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/approve| Field | Type | Required | Description |
|---|---|---|---|
note | string | No | Free-text note stored with the approval |
Withdraw your own approval (you cannot remove someone else's):
DELETE /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/approveBoth return the branch's current approval decision:
{ "approval": { "allowed": false, "risk": "...", "reasons": ["..."], "requirements": [] } }Auth and errors
Same gate as merge: reviewer, admin, or owner role (403). The caller's account must have an email address (400), and the project must be on the review workflow, which requires a plan that includes it (400 on an auto-merge project). A policy may narrow who counts by role; an approval from a role the policy does not accept is listed in rejectedGrants instead of counting.
Request Changes
Send a pending branch back to its author with a comment. The branch stays open; merging or rejecting it clears the request.
POST /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/request-changes| Field | Type | Required | Description |
|---|---|---|---|
comment | string | Yes | What should change (trimmed, max 4000 characters) |
{
"branch": "cr/content/blog-post/en/1774800862-27c1",
"changesRequested": {
"comment": "Shorten the intro",
"requestedBy": "user-id",
"requestedAt": "2026-01-15T12:00:00.000Z"
}
}Requires reviewer, admin, or owner role (403); 400 if comment is empty or the branch is not a cr/* branch. A branch.changes_requested webhook event is emitted.
Mark the request as addressed:
DELETE /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/request-changesAny project member can resolve it (the author usually does). Returns { "branch": "...", "resolved": true }, or 404 if the branch has no open change request. The row is kept as history until the branch is merged or rejected.
Reject Branch
Reject and delete a cr/* branch, discarding all changes.
POST /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/rejectResponse
{
"rejected": true
}Auth
Requires reviewer, admin, or owner role (403 otherwise). The permanent contentrain branch cannot be rejected (403), and any other non-cr/* branch returns 400. Rejecting also discards any approvals recorded for the branch.
Branch Health
Get branch health metrics for the project.
GET /api/workspaces/:workspaceId/projects/:projectId/branches/healthAny project member. Returns the pending-branch health plus the content-sync state:
{
"status": "ok",
"unmergedCount": 3,
"lastChecked": "2026-01-15T12:00:00.000Z",
"sync": { "...": "content-sync state, or null" }
}status is ok, warning, or blocked, based on the number of unmerged cr/* branches.
Branch Cleanup
Delete merged cr/* branches that are past the retention period.
POST /api/workspaces/:workspaceId/projects/:projectId/branches/cleanupRequires workspace owner or admin role. Returns the cleanup report:
{ "deleted": ["cr/content/blog-post/en/..."], "remaining": 2, "status": "ok" }Related Pages
- Content API -- content operations that create branches
- Chat API -- agent tools for branch management
- Content Engine -- branch operations internals