Skip to content

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:

  1. contentrain -- the SSOT (Single Source of Truth) branch for content
  2. cr/* -- 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/branches

Auth ​

Any project member.

Response ​

json
{
  "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/diff

Any 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/diff

Response (default) ​

The semantic review of the branch, plus the caller's review state:

FieldDescription
branch, info, groups, schema, settings, unclassified, summaryThe 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, canRejectWhether the caller may merge or reject the branch
canRequestChangestrue if the caller may request changes
changesRequested{ comment, requestedBy, requestedAt } while a change request is open, otherwise null
approvalThe 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)
approvedByRecorded approvals: [{ approver, at, note }]

Response (?raw=1) ​

json
{
  "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/merge

The :branch segment is percent-encoded (see URL Encoding).

Response ​

json
{
  "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 ​

StatusCondition
400Not a cr/* branch
403Caller cannot merge, or the approval policy is not satisfied. The latter returns data.approval with the policy decision (reasons, requirements)
409The branch got a new commit after it was approved. The merge is pinned to the approved tip, so review the new changes first
503The 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
FieldTypeRequiredDescription
notestringNoFree-text note stored with the approval

Withdraw your own approval (you cannot remove someone else's):

DELETE /api/workspaces/:workspaceId/projects/:projectId/branches/:branch/approve

Both return the branch's current approval decision:

json
{ "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
FieldTypeRequiredDescription
commentstringYesWhat should change (trimmed, max 4000 characters)
json
{
  "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-changes

Any 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/reject

Response ​

json
{
  "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/health

Any project member. Returns the pending-branch health plus the content-sync state:

json
{
  "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/cleanup

Requires workspace owner or admin role. Returns the cleanup report:

json
{ "deleted": ["cr/content/blog-post/en/..."], "remaining": 2, "status": "ok" }

Released under the AGPL-3.0 License. Privacy