StudioHomepage
ServicesCatalogHTTP APIMerges

Merge commits

POST
/api/catalog/projects/{project_id}/merges

Do a three-way merge, or examine a merge before you do it. When dryRun is true, the merge is not published. Conflicts are part of the response. You must have permission to merge in the project and to change each resource that the merge changes.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Path Parameters

project_id*string

Owning project identifier. Nonempty, at most 128 UTF-8 bytes, with no control characters. Project creation belongs to the project service.

Request Body

application/json
  1. body

Assess or publish a three-way merge. dryRun defaults to false. Both expected heads are required when supplying participant resolutions so assessment and publication use identical heads. Source selector resolves once. Multiple best common ancestors produce AmbiguousMergeBase. Catalog coordinates pointers and namespace constraints without initializing a query engine. resourceResolutions is required, may be empty, and is bounded to 1000 entries; message and retry bounds match PublishRequest.

dryRun?boolean|null
expectedSourceCommitId?|null
expectedTargetCommitId?|null
idempotencyKey*catalog.IdempotencyKey

Nonempty opaque retry key, at most 128 UTF-8 bytes, scoped to project and authenticated actor. Identical retries return the saved result; reuse for a different operation or request is rejected.

message?string|null
resourceResolutions*array<>
source*||

A commit identity or a movable branch/immutable tag resolved exactly once per request. Relative expressions such as main~3 are not supported.

targetBranchId*catalog.BranchId

Stable UUIDv7 branch identity. Rename preserves identity; deletion tombstones it.

Formatuuid
transactionId*catalog.TransactionId

Caller-allocated UUIDv7 publication identity used to recover an uncertain result within a project and authenticated actor scope.

Formatuuid

Response Body

Success

application/json
  1. response

Mergeable is the successful dry-run assessment; published is an atomic merge commit with target first parent and source second parent. Conflicts are response data and publish nothing.

alreadyUpToDate*
type*unknown
curl -X POST 'https://api.spiraldb.dev/api/catalog/projects/string/merges' \  -H 'Content-Type: application/json' \  -d '{  "idempotencyKey": "string",  "resourceResolutions": [    {      "base": "830379dd-657d-4fd3-bcb8-3466fa8332bb",      "ours": "3a6c0eb9-8e25-4ac8-8a08-0f58b92f8d7a",      "replacement": "0d5797a7-50c5-42e4-893d-e90cf0476063",      "resourceId": "026d60bb-63a8-407e-bf67-01dcfc6022e6",      "theirs": "acbf6d9a-fe71-46fa-9a24-58aa0444eec3"    }  ],  "source": {    "branch": {      "branch": "string"    },    "type": "branch"  },  "targetBranchId": "c5fd579d-68b4-4cee-8a65-9894272db901",  "transactionId": "75906707-8c31-479c-b354-aa805c4cefbc"}'
{  "alreadyUpToDate": {    "sourceCommitId": "2039dad8-6860-4074-ae75-96b269f429ac",    "targetCommitId": "fd08c3d1-74ab-47e2-b0e2-ee0fb24af00d"  },  "type": "alreadyUpToDate"}