Skip to content

fix(API): branching: align operations with the backend behavior #1136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sven Dunemann (forelabs) merged 2 commits into from
May 20, 2026
Merged

fix(API): branching: align operations with the backend behavior #1136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4f34806
docs(branches): align operations with controller behavior
claude May 19, 2026
42763b3
chore: recompile bundled JSON
forelabs May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 111 additions & 12 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3631,6 +3631,11 @@
"name": {
"type": "string"
},
"base": {
"type": "string",
"nullable": true,
"description": "Name of the base branch this branch was created from. Only present for branches created with the newer branching system."
},
"created_at": {
"type": "string",
"format": "date-time"
Expand All @@ -3650,7 +3655,16 @@
"$ref": "#/components/schemas/user_preview"
},
"state": {
"type": "string"
"type": "string",
"enum": [
"creating_branch",
"merging_branch",
"syncing_branch",
"merged",
"success",
"branch_error",
"merge_conflict"
]
},
"child_branches": {
"type": "array",
Expand Down Expand Up @@ -18393,7 +18407,7 @@
"/projects/{project_id}/branches": {
"get": {
"summary": "List branches",
"description": "List all branches the of the current project.",
"description": "List all branches of the current project.\n\nRequires the Branching feature to be enabled on the account.\n",
"operationId": "branches/list",
"tags": [
"Branches"
Expand Down Expand Up @@ -18446,6 +18460,13 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `read` scope, when the user is not allowed to read branches in this project, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
Expand All @@ -18467,7 +18488,7 @@
},
"post": {
"summary": "Create a branch",
"description": "Create a new branch.\n\n*Note: Creating a new branch may take several minutes depending on the project size.*\n",
"description": "Create a new branch.\n\nBranch project provisioning runs asynchronously, so the newly created branch is returned in a transitional state (typically `creating_branch`) and only reaches `success` once the underlying project has been set up. Poll the branch resource until its `state` becomes `success` before performing further operations on it.\n\nRequires the Branching feature to be enabled on the account.\n\n*Note: Creating a new branch may take several minutes depending on the project size.*\n",
"operationId": "branch/create",
"tags": [
"Branches"
Expand Down Expand Up @@ -18505,9 +18526,19 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to create branches in this project, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
"422": {
"$ref": "#/components/responses/422"
},
"429": {
"$ref": "#/components/responses/429"
}
Expand Down Expand Up @@ -18537,6 +18568,11 @@
"description": "Name of the branch",
"type": "string",
"example": "my-branch"
},
"base": {
"description": "Name of an existing branch to use as the base for the new branch.",
"type": "string",
"example": "parent-branch"
}
}
}
Expand All @@ -18549,7 +18585,7 @@
"/projects/{project_id}/branches/{name}": {
"get": {
"summary": "Get a single branch",
"description": "Get details on a single branch for a given project.",
"description": "Get details on a single branch for a given project.\n\nRequires the Branching feature to be enabled on the account.\n",
"operationId": "branch/show",
"tags": [
"Branches"
Expand Down Expand Up @@ -18590,6 +18626,13 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `read` scope, when the user is not allowed to read this branch, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
Expand All @@ -18611,7 +18654,7 @@
},
"patch": {
"summary": "Update a branch",
"description": "Update an existing branch.",
"description": "Update an existing branch. Only the branch name can be changed.\n\nRequires the Branching feature to be enabled on the account.\n",
"operationId": "branch/update",
"tags": [
"Branches"
Expand Down Expand Up @@ -18652,9 +18695,19 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to update this branch, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
"422": {
"$ref": "#/components/responses/422"
},
"429": {
"$ref": "#/components/responses/429"
}
Expand Down Expand Up @@ -18691,7 +18744,7 @@
},
"delete": {
"summary": "Delete a branch",
"description": "Delete an existing branch.",
"description": "Delete an existing branch.\n\nA branch cannot be deleted while it still has open jobs or open translation orders attached to its branch project — in that case the request is rejected with `409 Conflict`. A branch whose current `state` does not allow deletion (for example, while a merge or sync is in progress) is rejected with `422 Unprocessable Entity`.\n\nRequires the Branching feature to be enabled on the account.\n",
"operationId": "branch/delete",
"tags": [
"Branches"
Expand All @@ -18714,9 +18767,23 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to delete this branch, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
"409": {
"$ref": "#/components/responses/409",
"description": "Conflict. The branch has open jobs or open translation orders. The response body lists the blockers, for example `{\"errors\":[\"open_jobs\",\"open_orders\"]}`. Close or complete the listed resources before retrying."
},
"422": {
"$ref": "#/components/responses/422"
},
"429": {
"$ref": "#/components/responses/429"
}
Expand All @@ -18737,7 +18804,7 @@
"/projects/{project_id}/branches/{name}/merge": {
"patch": {
"summary": "Merge a branch",
"description": "Merge an existing branch.\n\n*Note: Merging a branch may take several minutes depending on diff size.*\n",
"description": "Merge an existing branch back into its base branch.\n\nThe merge runs asynchronously. The branch transitions to `merging_branch` and settles in `merged`, `merge_error`, or `merge_conflict` once the background job completes; the response body for this request is empty. Poll the branch resource to observe the final state.\n\nA branch cannot be merged while it still has open jobs or open translation orders attached to its branch project — in that case the request is rejected with `409 Conflict`. A branch whose current `state` does not allow a merge is rejected with `422 Unprocessable Entity`.\n\nRequires the Branching feature to be enabled on the account.\n\n*Note: Merging a branch may take several minutes depending on diff size.*\n",
"operationId": "branch/merge",
"tags": [
"Branches"
Expand All @@ -18755,7 +18822,7 @@
],
"responses": {
"200": {
"description": "OK",
"description": "OK. The merge has been scheduled. The response body is empty; observe progress by polling the branch resource.",
"headers": {
"X-Rate-Limit-Limit": {
"$ref": "#/components/headers/X-Rate-Limit-Limit"
Expand All @@ -18771,9 +18838,23 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to merge this branch, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
"409": {
"$ref": "#/components/responses/409",
"description": "Conflict. The branch has open jobs or open translation orders. The response body lists the blockers, for example `{\"errors\":[\"open_jobs\",\"open_orders\"]}`. Close or complete the listed resources before retrying."
},
"422": {
"$ref": "#/components/responses/422"
},
"429": {
"$ref": "#/components/responses/429"
}
Expand All @@ -18797,8 +18878,12 @@
"title": "branch/merge/parameters",
"properties": {
"strategy": {
"description": "strategy used for merge conflicts, use_main or use_branch",
"description": "Conflict resolution strategy applied when the branch and its base have diverged. `use_main` keeps the values from the base branch; `use_branch` keeps the values from the branch being merged.\n",
"type": "string",
"enum": [
"use_main",
"use_branch"
],
"example": "use_main"
}
}
Expand All @@ -18811,7 +18896,7 @@
"/projects/{project_id}/branches/{name}/sync": {
"patch": {
"summary": "Sync a branch",
"description": "Sync an existing branch.\n\n*Note: Only available for branches created with new branching.*\n",
"description": "Pull changes from the base branch into this branch, applying the chosen conflict-resolution strategy.\n\nThe sync runs asynchronously. The branch transitions to `syncing_branch` and settles back into `success` (or `merge_conflict` / `branch_error`) once the background job completes; the response body for this request is empty. Poll the branch resource to observe the final state.\n\nOnly branches created with the newer branching system can be synced. Requests against branches from the older system, or against branches whose current state does not allow a sync, are rejected with `422 Unprocessable Entity` and an empty body.\n\nRequires the Branching feature to be enabled on the account.\n",
"operationId": "branch/sync",
"tags": [
"Branches"
Expand All @@ -18829,7 +18914,7 @@
],
"responses": {
"200": {
"description": "OK",
"description": "OK. The sync has been scheduled. The response body is empty; observe progress by polling the branch resource.",
"headers": {
"X-Rate-Limit-Limit": {
"$ref": "#/components/headers/X-Rate-Limit-Limit"
Expand All @@ -18845,9 +18930,19 @@
"400": {
"$ref": "#/components/responses/400"
},
"401": {
"$ref": "#/components/responses/401"
},
"403": {
"$ref": "#/components/responses/403",
"description": "Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to sync this branch, or when the Branching feature is not available on the account."
},
"404": {
"$ref": "#/components/responses/404"
},
"422": {
"$ref": "#/components/responses/422"
},
"429": {
"$ref": "#/components/responses/429"
}
Expand All @@ -18871,8 +18966,12 @@
"title": "branch/sync/parameters",
"properties": {
"strategy": {
"description": "strategy used for conflicts, use_main or use_branch",
"description": "Conflict resolution strategy applied when the branch and its base have diverged. `use_main` keeps the values from the base branch; `use_branch` keeps the values from this branch.\n",
"type": "string",
"enum": [
"use_main",
"use_branch"
],
"example": "use_main"
}
}
Expand Down
17 changes: 16 additions & 1 deletion paths/branches/create.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@
summary: Create a branch
description: |
Create a new branch.


Branch project provisioning runs asynchronously, so the newly created branch is returned in a transitional state (typically `creating_branch`) and only reaches `success` once the underlying project has been set up. Poll the branch resource until its `state` becomes `success` before performing further operations on it.

Requires the Branching feature to be enabled on the account.

*Note: Creating a new branch may take several minutes depending on the project size.*
operationId: branch/create
tags:
Expand All @@ -26,8 +30,15 @@ responses:
"$ref": "../../headers.yaml#/X-Rate-Limit-Reset"
'400':
"$ref": "../../responses.yaml#/400"
'401':
"$ref": "../../responses.yaml#/401"
'403':
"$ref": "../../responses.yaml#/403"
description: Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to create branches in this project, or when the Branching feature is not available on the account.
'404':
"$ref": "../../responses.yaml#/404"
'422':
"$ref": "../../responses.yaml#/422"
'429':
"$ref": "../../responses.yaml#/429"
x-code-samples:
Expand Down Expand Up @@ -58,4 +69,8 @@ requestBody:
description: Name of the branch
type: string
example: my-branch
base:
description: Name of an existing branch to use as the base for the new branch.
type: string
example: parent-branch
x-cli-version: '2.5'
17 changes: 16 additions & 1 deletion paths/branches/destroy.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,11 @@
---
summary: Delete a branch
description: Delete an existing branch.
description: |
Delete an existing branch.

A branch cannot be deleted while it still has open jobs or open translation orders attached to its branch project — in that case the request is rejected with `409 Conflict`. A branch whose current `state` does not allow deletion (for example, while a merge or sync is in progress) is rejected with `422 Unprocessable Entity`.

Requires the Branching feature to be enabled on the account.
operationId: branch/delete
tags:
- Branches
Expand All @@ -13,8 +18,18 @@ responses:
"$ref": "../../responses.yaml#/204"
'400':
"$ref": "../../responses.yaml#/400"
'401':
"$ref": "../../responses.yaml#/401"
'403':
"$ref": "../../responses.yaml#/403"
description: Forbidden. Returned when the access token lacks the `write` scope, when the user is not allowed to delete this branch, or when the Branching feature is not available on the account.
'404':
"$ref": "../../responses.yaml#/404"
'409':
"$ref": "../../responses.yaml#/409"
description: Conflict. The branch has open jobs or open translation orders. The response body lists the blockers, for example `{"errors":["open_jobs","open_orders"]}`. Close or complete the listed resources before retrying.
'422':
"$ref": "../../responses.yaml#/422"
'429':
"$ref": "../../responses.yaml#/429"
x-code-samples:
Expand Down
10 changes: 9 additions & 1 deletion paths/branches/index.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
---
summary: List branches
description: List all branches the of the current project.
description: |
List all branches of the current project.

Requires the Branching feature to be enabled on the account.
operationId: branches/list
tags:
- Branches
Expand Down Expand Up @@ -31,6 +34,11 @@ responses:
"$ref": "../../headers.yaml#/Pagination"
'400':
"$ref": "../../responses.yaml#/400"
'401':
"$ref": "../../responses.yaml#/401"
'403':
"$ref": "../../responses.yaml#/403"
description: Forbidden. Returned when the access token lacks the `read` scope, when the user is not allowed to read branches in this project, or when the Branching feature is not available on the account.
'404':
"$ref": "../../responses.yaml#/404"
'429':
Expand Down
Loading
Loading