{ "openapi": "3.1.0", "info": { "title": "Localisync Branch Management API", "version": "1.0.0", "description": "Branch management, immutable snapshot comparisons and atomic merges. Every project has fixed main. All members can read and compare; Owner/Admin/Editor fork; Editors rename their own branches; Owner/Admin manage lifecycle, resolutions and merges. Session authentication, current membership, Origin and CSRF are required. No publishing or distribution is triggered." }, "paths": { "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches": { "get": { "operationId": "listBranches", "summary": "List branches", "description": "List branches.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "schema": { "enum": [ "active", "archived", "all" ], "default": "active" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branches" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "forkBranch", "summary": "Create a branch from a snapshot", "description": "Owner/Admin/Editor. Source token must match. Copies all keys, languages, tags and file identities, including archived or inactive content; transfer jobs and private files are not copied. Limits: 10,000 keys, 50,000 values, 100 MiB.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fork" } } } }, "responses": { "202": { "description": "Operation queued; poll its state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{id}": { "get": { "operationId": "getBranch", "summary": "Read a branch", "description": "Read a branch.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "renameBranch", "summary": "Rename a branch", "description": "Owner/Admin, or Editor who created this active branch. Main is protected. Names are case-insensitively unique per project; slash characters are supported, UUIDs address resources.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rename" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteBranch", "summary": "Permanently delete an archived branch", "description": "Owner/Admin; archived non-main only. Name must match exactly. Nonterminal jobs must complete or be cancelled. Shared history and snapshots remain protected; live content and temporary outputs are removed. No undo.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Rename" } } } }, "responses": { "202": { "description": "Operation queued; poll its state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{id}/archive": { "post": { "operationId": "archiveBranch", "summary": "Archive a branch", "description": "Owner/Admin only. Main cannot be archived. Archived branches remain readable, comparable and exportable.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{id}/restore": { "post": { "operationId": "restoreBranch", "summary": "Restore a branch", "description": "Owner/Admin only. Main cannot be archived. Archived branches remain readable, comparable and exportable.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Branch" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons": { "post": { "operationId": "compareBranches", "summary": "Compare source with target", "description": "All members. Direction matters. Uses every best common ancestor. Preview is immutable and expires after 24 hours. No automatic text merging.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Compare" } } } }, "responses": { "202": { "description": "Operation queued; poll its state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons/{id}": { "get": { "operationId": "getBranchComparison", "summary": "Read comparison status", "description": "Read comparison status.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons/{id}/changes": { "get": { "operationId": "listBranchChanges", "summary": "List comparison changes", "description": "List comparison changes.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "q", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "locale", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "kind", "in": "query", "schema": { "type": "string", "default": "" } }, { "name": "tag", "in": "query", "description": "Literal case-insensitive tag name substring, including tags attached to changed keys in base, source or target.", "schema": { "type": "string", "maxLength": 50 } }, { "name": "conflicts", "in": "query", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changes" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons/{id}/issues": { "get": { "operationId": "listBranchComparisonIssues", "summary": "Read comparison integrity issues", "description": "Read comparison integrity issues.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issues" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons/{id}/resolutions": { "patch": { "operationId": "resolveBranchConflicts", "summary": "Save versioned conflict resolutions", "description": "Owner/Admin. Select source or target; custom results are limited to values, names, definitions and language configuration. Saves choices and queues validation. Failed validation retains the choices. Never reuse decisions on a new preview.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Resolve" } } } }, "responses": { "202": { "description": "Operation queued; poll its state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-comparisons/{id}/apply": { "post": { "operationId": "mergeBranches", "summary": "Apply a reviewed comparison", "description": "Owner/Admin; active target and parents required. Every conflict and integrity issue must be resolved. Snapshot freshness and permissions are rechecked under ordered locks. Content, history, graph edges, audit and success commit atomically. Retries never apply twice.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "responses": { "202": { "description": "Operation queued; poll its state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-jobs": { "get": { "operationId": "listBranchJobs", "summary": "List branch operations", "description": "List branch operations.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Jobs" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-jobs/{id}": { "get": { "operationId": "getBranchJob", "summary": "Read branch operation status", "description": "Read branch operation status.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-jobs/{id}/issues": { "get": { "operationId": "listBranchJobIssues", "summary": "Read branch operation issues", "description": "Read branch operation issues.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Issues" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-jobs/{id}/cancel": { "post": { "operationId": "cancelBranchJob", "summary": "Cancel an eligible branch operation", "description": "Creator or Owner/Admin. Queued, ready, failed or conflict operations can be cancelled. Processing and committed operations cannot be cancelled.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/workspaces/{workspaceId}/projects/{projectId}/branch-jobs/{id}/retry": { "post": { "operationId": "retryBranchJob", "summary": "Retry a temporary branch operation failure", "description": "Creator or Owner/Admin; only processing_failed errors are retryable. Access or content conflicts require a new reviewed operation.", "security": [ { "session": [] } ], "parameters": [ { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Origin", "in": "header", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "X-CSRF-Token", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "responses": { "202": { "description": "Operation queued; poll its state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BranchJob" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Sign in required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient current workspace role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Resource unavailable in this scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version conflict, stale preview or content invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Request limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Service unavailable; success is not implied.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "schemas": { "Branch": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "isMain": { "type": "boolean" }, "createdBy": { "type": "string", "format": "uuid" }, "creatorEmail": { "type": "string" }, "sourceBranchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "sourceBranchName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "headId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "token": { "type": "string", "pattern": "^[0-9]+$" }, "blockers": { "type": "object", "description": "Detail responses include deletion blockers. Lists contain up to 25 operations. Assistance jobs are visible to their creator or workspace managers; counts include all unfinished operations and active calls.", "properties": { "branchCount": { "type": "integer" }, "transferCount": { "type": "integer" }, "branchJobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "kind", "state" ] } }, "transferJobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "kind", "state" ] } }, "assistanceCount": { "type": "integer", "minimum": 0 }, "assistanceJobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string" } }, "required": [ "id", "state" ] } } }, "required": [ "branchCount", "transferCount", "branchJobs", "transferJobs", "assistanceCount", "assistanceJobs" ] } }, "required": [ "id", "workspaceId", "projectId", "name", "isMain", "createdBy", "creatorEmail", "sourceBranchId", "sourceBranchName", "version", "archivedAt", "createdAt", "headId", "token" ] }, "BranchJob": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "kind": { "enum": [ "fork", "compare", "merge", "delete" ] }, "state": { "enum": [ "queued", "processing", "ready", "completed", "failed", "conflict", "cancelled", "expired" ] }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "summary": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "resultBranchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "appliedJobId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "sourceBranchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "targetBranchId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "actorId": { "type": "string", "format": "uuid" } }, "required": [ "id", "workspaceId", "projectId", "kind", "state", "version", "summary", "resultBranchId", "appliedJobId", "errorCode", "createdAt", "expiresAt", "sourceBranchId", "targetBranchId", "actorId" ] }, "Cell": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "present": { "const": false } }, "required": [ "present" ] }, { "type": "object", "additionalProperties": false, "properties": { "present": { "const": true }, "value": {} }, "required": [ "present", "value" ] } ] }, "Change": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "enum": [ "language", "tag", "definition", "archive", "value", "assignment", "binding" ] }, "keyId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "keyName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tagId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "bases": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Cell" } }, "source": { "$ref": "#/components/schemas/Cell" }, "target": { "$ref": "#/components/schemas/Cell" }, "conflict": { "type": "boolean" }, "result": { "anyOf": [ { "$ref": "#/components/schemas/Cell" }, { "type": "null" } ] }, "tagNames": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "kind", "keyId", "keyName", "locale", "tagId", "bases", "source", "target", "conflict", "result", "tagNames" ] }, "Issue": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "keyId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "locale": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "code", "message", "keyId", "locale" ] }, "Version": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "version" ] }, "Branches": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Branch" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ] }, "Jobs": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BranchJob" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ] }, "Changes": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Change" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "items", "page", "pageSize", "hasMore", "version" ] }, "Issues": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "items", "page", "pageSize", "hasMore" ] }, "Fork": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceId": { "type": "string", "format": "uuid" }, "sourceToken": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "name", "sourceId", "sourceToken" ] }, "Rename": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "name", "version" ] }, "Compare": { "type": "object", "additionalProperties": false, "properties": { "sourceId": { "type": "string", "format": "uuid" }, "targetId": { "type": "string", "format": "uuid" } }, "required": [ "sourceId", "targetId" ] }, "Resolve": { "type": "object", "additionalProperties": false, "properties": { "version": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "resolutions": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "choice": { "enum": [ "source", "target" ] } }, "required": [ "id", "choice" ] }, { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string" }, "choice": { "const": "custom" }, "value": {} }, "required": [ "id", "choice", "value" ] } ] } } }, "required": [ "version", "resolutions" ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "string", "enum": [ "unauthorized", "forbidden", "invalid_request", "not_found", "conflict", "rate_limited", "unavailable" ] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "details": { "type": "object", "additionalProperties": false, "properties": { "dependentLocales": { "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 255 } } }, "required": [ "dependentLocales" ] } }, "required": [ "error", "message" ] } }, "securitySchemes": { "session": { "type": "apiKey", "in": "cookie", "name": "__Host-localisync-session" } } } }