API

Every public Mergestorm endpoint: 56 operations across 12 groups. The mg CLI and the MCP server call these same endpoints, so anything they do, you can do over HTTP.

Base URL: https://api.mergestorm.ai. This page is generated from docs/openapi.v1.yaml (OpenAPI 3.1), which tests keep in step with the server's routes.

Authentication

Send an API key as a Bearer token on every request: Authorization: Bearer msk_live_…. Keys belong to one account and can do anything that account can.

mg login opens the browser, and after you approve it stores a new key for the CLI. An agent runs mg login --start, sends you the link, then runs mg login --finish.
For your own scripts, create a key on Settings → API. The full key is shown once.

The API keys and CLI sign-in endpoints are the exception: they use the dashboard session cookie, because they are how a key gets made.

CLI and MCP

The mergestorm CLI (also mg) wraps this API for terminals and agents. It needs Node.js 22 or newer.

curl -fsSL https://mergestorm.ai/install.sh | bash   # or: npm install -g mergestorm
mg login
mg stack create feat/my-first-layer
git commit -am "feat: first layer"
mg stack submit

Agents can use the hosted MCP server at https://api.mergestorm.ai/api/v1/mcp with the same key, or run it locally with claude mcp add mergestorm -- npx -y mergestorm-mcp.

Tutorial: stacked PRs with mg
CLI commands for stacks
CLI source on GitHub (MIT) and npm package
llms.txt for agents

Errors

Errors return a JSON body with a machine-readable error code and a readable message:

{ "error": "invalid_input", "message": "owner and repo are required" }

401 means the key is missing, wrong or revoked. 429 means a rate limit was hit; wait for the number of seconds in the Retry-After header.

Rate limits

Limits apply per API key unless the name says otherwise. GET requests use the read budget. Requests that start work, such as reviews, agent jobs and issues, use the submit budget.

`submit_per_key`	10 per 1 min
`read_per_key`	300 per 1 min
`auth_failures_per_ip`	30 per 1 min
`device_start_per_ip`	10 per 10 min
`device_token_per_ip_and_code`	20 per 1 min
`in_flight_per_account`	5 at once, retry after 30 s

Reviews

Review a diff or a set of files without opening a pull request. Reviews run on the same engine as pull request reviews and debit review credits. Reviews with the same thread name are grouped into a thread.

List recent review jobs

GET/api/v1/reviews

Auth: API key

Parameters

Name	In	Type	Description
`limit`	query	`integer`	default 10 · min 1 · max 50

Responses

200 Recent Review Jobs.

object

Field	Type	Description
`items`required	`array of ReviewJobListItem`

401 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/reviews' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Submit a diff or files for review

POST/api/v1/reviews

Auth: API key

Request body

CreateReviewRequest

Field	Type	Description
`thread`required	`string`	min length 1 · max length 120 · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]{0,119}$
`diff`	`string`	Capped at 1,000,000 UTF-8 bytes at runtime; maxLength 250000 guarantees that byte budget.min length 1 · max length 250000
`files`	`array of ReviewFile`	Files to review; at least one non-empty path/content pair, up to 2,000,000 content characters total.min items 1 · max items 40
`base_label`	`string`	max length 200
`head_label`	`string`	max length 200
`context`	`string`	max length 60000
`context_files`	`array of ReviewFile`	Context files; up to 16,000 content characters per file and 60,000 total. Oversized entries are truncated at runtime.max items 10
`router_mode`	`RouterMode (enum)`
`specialists`	`array of Specialist (enum)`	max items 5
`webhook_url`	`string (uri)`
`webhook_secret`	`string`	max length 128
`idempotency_key`	`string`	max length 128
`owner`	`string`	Repo owner, used with `repo` for thread identity.max length 200
`repo`	`string`	Repo slug (`owner/name`) or repo name when `owner` is set.max length 200
`branch`	`string`	Branch name, used for thread identity.max length 200
`recheck`	`object`	Thin recheck selectors. At least one selector array must be non-empty.
`recheck.finding_keys`	`array of string`	max items 40
`recheck.paths`	`array of string`	max items 40
`recheck.specialists`	`array of Specialist (enum)`	max items 5

One of: requires diff

One of: requires files

Responses

200 Review Job.

ReviewJob

Field	Type	Description
`job_id`required	`string`
`thread_id`required	`string \| null`
`thread_slug`required	`string \| null`
`thread_job_number`required	`integer \| null`
`status`required	`JobStatus (enum)`
`base_label`required	`string \| null`
`head_label`required	`string \| null`
`router_mode`required	`RouterMode (enum)`
`specialists_requested`required	`array of Specialist (enum)`
`specialists_run`required	`array of string \| null`
`credits`required	`Credits`
`summary`required	`string \| null`
`verdict`required	`Verdict (enum)`
`truncated`required	`boolean`
`findings`required	`Findings`
`recheck`	`ReviewRecheck`	Present only for thin-recheck jobs; omitted for ordinary jobs.
`error`required	`string \| null`
`created_at`required	`string (date-time)`
`started_at`required	`string (date-time) \| null`
`finished_at`required	`string (date-time) \| null`

202 Accepted; webhook_secret is create-response-only.

object

Field	Type	Description
`job_id`required	`string`
`thread_id`required	`string \| null`
`thread_slug`required	`string \| null`
`thread_job_number`required	`integer \| null`
`status`required	`JobStatus (enum)`
`base_label`required	`string \| null`
`head_label`required	`string \| null`
`router_mode`required	`RouterMode (enum)`
`specialists_requested`required	`array of Specialist (enum)`
`specialists_run`required	`array of string \| null`
`credits`required	`Credits`
`summary`required	`string \| null`
`verdict`required	`Verdict (enum)`
`truncated`required	`boolean`
`findings`required	`Findings`
`recheck`	`ReviewRecheck`	Present only for thin-recheck jobs; omitted for ordinary jobs.
`error`required	`string \| null`
`created_at`required	`string (date-time)`
`started_at`required	`string (date-time) \| null`
`finished_at`required	`string (date-time) \| null`
`webhook_secret`	`string`	Returned only on create when `webhook_url` was requested.

400 401 402 413 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/reviews' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "thread": "<thread>",
  "diff": "<diff>"
}'

Read one review job and its findings

GET/api/v1/reviews/{job_id}

Auth: API key

Parameters

Name	In	Type	Description
`job_id`required	path	`string`

Responses

200 Review Job.

ReviewJob

Field	Type	Description
`job_id`required	`string`
`thread_id`required	`string \| null`
`thread_slug`required	`string \| null`
`thread_job_number`required	`integer \| null`
`status`required	`JobStatus (enum)`
`base_label`required	`string \| null`
`head_label`required	`string \| null`
`router_mode`required	`RouterMode (enum)`
`specialists_requested`required	`array of Specialist (enum)`
`specialists_run`required	`array of string \| null`
`credits`required	`Credits`
`summary`required	`string \| null`
`verdict`required	`Verdict (enum)`
`truncated`required	`boolean`
`findings`required	`Findings`
`recheck`	`ReviewRecheck`	Present only for thin-recheck jobs; omitted for ordinary jobs.
`error`required	`string \| null`
`created_at`required	`string (date-time)`
`started_at`required	`string (date-time) \| null`
`finished_at`required	`string (date-time) \| null`

401 404 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/reviews/<job_id>' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

List review threads

GET/api/v1/threads

Auth: API key

Parameters

Name	In	Type	Description
`limit`	query	`integer`	default 20 · min 1 · max 50

Responses

200 Recently active review threads.

object

Field	Type	Description
`items`required	`array of ThreadListItem`

401 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/threads' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Read one review thread

GET/api/v1/threads/{slug}

Auth: API key

Parameters

Name	In	Type	Description
`slug`required	path	`string`

Responses

200 Active thread and recent job timeline.

Thread

Field	Type	Description
`thread_id`required	`string`
`slug`required	`string`
`source`required	`"api" \| "github"`
`branch`required	`string \| null`
`owner`required	`string \| null`
`repo`required	`string \| null`
`pr_number`required	`integer \| null`
`status`required	`string`
`pr_linked_at`required	`string (date-time) \| null`
`job_count`required	`integer`
`created_at`required	`string (date-time)`
`jobs`required	`array of ThreadJob`

401 404 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/threads/<slug>' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Pull request reviews

Read and dismiss Vortex reviews of open pull requests, and wake a Breeze chat when one finishes.

Read the latest Vortex review of a pull request

GET/api/v1/stacks/pr-review

Auth: API key

pass and after_pass are exclusive and require after_sha. Reads latest matching attempt. A resting result with newer_pass_pending=true must continue polling. Access remains scoped to the bearer account and authorized monitored-repository review visibility.

Parameters

Name	In	Type	Description
`owner`required	query	`string`
`repo`required	query	`string`
`pr_number`required	query	`integer`	min 1
`after_sha`	query	`string`	pattern ^[0-9a-fA-F]{7,}$
`pass`	query	`integer`	min 1
`after_pass`	query	`integer`	min 1
`wait`	query	`integer`	Long poll timeout in seconds.default 0 · min 0 · max 45

Responses

200 Successful response.

StackPrReview

Field	Type	Description
`schema`required	`"mergestorm.pr_review/v1"`
`id`required	`string`
`owner`required	`string`
`repo`required	`string`
`pr_number`required	`number`
`status`required	`string`
`raw_status`required	`string`
`phase`required	`null \| string`
`verdict`required	`null \| string`
`head_sha`required	`null \| string`
`pass`required	`number`
`review_count`required	`number`
`skip_reason`required	`null \| string`
`reviewed_at`required	`null \| string`
`finding_count`required	`null \| number`
`findings`required	`null \| ReviewFindings`
`dismissed_findings`required	`array of object`
`dismissed_findings.path`required	`string`
`dismissed_findings.line`required	`number`
`dismissed_findings.title`required	`string`
`dismissed_findings.severity`required	`"error" \| "info" \| "warning"`
`dismissed_findings.finding_key`required	`string`
`dismissed_findings.github_comment_id`required	`null \| number`
`patch_policy`required	`null \| ReviewPatchPolicy`
`newer_pass_pending`	`true`

400 401 404 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/stacks/pr-review?owner=%3Cowner%3E&repo=%3Crepo%3E&pr_number=1' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Wake a Breeze chat when a Vortex review or a stack finishes

POST/api/v1/stacks/chat-waits

Auth: API key

Records that a Breeze chat waits on a Vortex review of a pull request (at a head and from a pass) or on a stack's merge queue entry. When it finishes, the chat gets a new turn with the result. Idempotent per chat and target.

Request body

StackChatWaitRequest

Field	Type	Description
`chat_id`required	`string (uuid)`
`kind`required	`"vortex" \| "stack"`
`owner`	`string`
`repo`	`string`
`pr_number`	`integer`	min 1
`head_sha`	`string`	pattern ^[0-9a-fA-F]{7,64}$
`min_pass`	`integer`	min 1
`stack_id`	`string (uuid)`

Responses

200 Successful response.

StackChatWait

Field	Type	Description
`result`required	`"waiting" \| "existing" \| "finished"`
`id`required	`string (uuid)`
`min_pass`	`integer \| null`

400 401 404 409 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/chat-waits' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "chat_id": "00000000-0000-4000-8000-000000000000",
  "kind": "vortex"
}'

Dismiss Vortex findings on a pull request

POST/api/v1/stacks/pr-review/dismiss

Auth: API key

Request body

StackDismissRequest

A write requires a reason whose trimmed, whitespace-normalized text has 20–4000 characters and at least three distinct words of three or more characters. Raw-text length bounds do not represent that normalization. findings scope requires finding_ids; review scope rejects them. Preview bypasses reason and scope/finding selection write requirements. Numeric comment ids are also accepted.

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`pr_number`required	`integer`	min 1
`head_sha`required	`string`	pattern ^[0-9a-fA-F]{40}$
`review_id`required	`integer`	min 1
`scope`	`"findings" \| "review"`	default "findings"
`finding_ids`	`array of string \| integer`	max items 50
`reason`	`string`
`evidence_url`	`string`	pattern ^https://\S{1,2000}$
`preview`	`boolean`	default false

Responses

200 Successful response.

FindingDismissResult

Field	Type	Description
`status`required	`"dismissed" \| "preview"`
`owner`required	`string`
`repo`required	`string`
`pr_number`required	`number`
`head_sha`required	`string`
`review_id`required	`number`
`review_kind`required	`"seam" \| "core"`
`scope`required	`"findings" \| "review"`
`dismissed`required	`array of FindingDismissFinding`
`already_dismissed`required	`array of object`
`already_dismissed.finding_id`required	`string`
`already_dismissed.finding_key`required	`string`
`already_dismissed.path`required	`null \| string`
`already_dismissed.line`required	`null \| number`
`already_dismissed.title`required	`string`
`already_dismissed.actor_login`required	`string`
`already_dismissed.dismissed_at`required	`string`
`remaining`required	`array of FindingDismissFinding`
`all_dismissed`required	`boolean`
`gate`required	`FindingDismissGate`
`stack_id`required	`null \| string`
`threads`required	`array of object`
`threads.finding_id`required	`string`
`threads.state`required	`"failed" \| "resolved" \| "already_resolved" \| "not_found"`

400 401 403 404 409 422 500 502 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/pr-review/dismiss' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "pr_number": 1,
  "head_sha": "<head_sha>",
  "review_id": 1
}'

Stacks

Stacks are chains of pull requests that Mergestorm reviews and lands layer by layer. These endpoints list, adopt, configure and repair them.

List the account's stacks

GET/api/v1/stacks

Auth: API key

Parameters

Name	In	Type	Description
`enrich`	query	`string`	1 or true requests GitHub enrichment; otherwise DB-only.

Responses

200 Successful response.

StackList

Field	Type	Description
`stacks`required	`array of StackDto`

401 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/stacks' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

List stacks with live GitHub state

GET/api/v1/stacks/enrich

Auth: API key

Parameters

Name	In	Type	Description
`stackId`	query	`string`

Responses

200 Successful response.

StackList

Field	Type	Description
`stacks`required	`array of StackDto`

401 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/stacks/enrich' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Change a stack's policy

PATCH/api/v1/stacks/{id}

Auth: API key

Only supplied policy keys are echoed. Null clears review/patch/conflict/CI overrides to account defaults. Auto land accepts only boolean. archived and unknown keys are rejected. Enabling Cyclone overrides requires a connected Cyclone account.

Parameters

Name	In	Type	Description
`id`required	path	`string`

Request body

StackPolicyRequest

Field	Type	Description
`autoEnqueueWhenReady`	`boolean`
`autoReviewOverride`	`boolean \| null`
`autoPatchOverride`	`boolean \| null`
`autoResolveConflictsOverride`	`boolean \| null`
`autoFixCiOverride`	`boolean \| null`

Responses

200 Successful response.

StackPolicyPatch

Field	Type	Description
`autoEnqueueWhenReady`	`boolean`
`autoReviewOverride`	`boolean \| null`
`autoPatchOverride`	`boolean \| null`
`autoResolveConflictsOverride`	`boolean \| null`
`autoFixCiOverride`	`boolean \| null`

400 401 404 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X PATCH 'https://api.mergestorm.ai/api/v1/stacks/<id>' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Adopt an open pull request chain as a stack

POST/api/v1/stacks/adopt

Auth: API key

Requires the bearer account infrastructure installation and uses its account policy and credits. Policy uses camelCase; MCP snake_case inputs are mapped by the shared client.

Parameters

Name	In	Type	Description
`x-mergestorm-chat-id`	header	`string (uuid)`	A Breeze chat of the caller. When the stack is registered, its pull request is linked to that chat and the chat follows the stack's landing and the pull request's Vortex reviews as background tasks. mg sends it from MERGESTORM_CHAT_ID.

Request body

StackAdoptRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`prNumber`required	`integer`	min 1
`autoEnqueueWhenReady`	`boolean`
`autoReviewOverride`	`boolean \| null`
`autoPatchOverride`	`boolean \| null`
`autoResolveConflictsOverride`	`boolean \| null`
`autoFixCiOverride`	`boolean \| null`

Responses

200 Successful response.

StackAdoptResponse

One of: Option 1

Field	Type	Description
`stack`required	`null \| EngineStackRecord`
`chain`required	`array of EngineStackLayer`

400 409 422 500 502 Adoption validation, installation, topology or control failure.
401 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/adopt' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "prNumber": 1
}'

Repair the stored display state of stacks

POST/api/v1/stacks/repair

Auth: API key

Request body

StackRepairRequest

Field	Type	Description
`stackId`	`string`

Responses

200 Successful response.

StackDisplayRepairResult

Field	Type	Description
`outcome`required	`"failed" \| "skipped" \| "complete" \| "partial"`
`stacks`required	`array of StackDto`
`repaired`required	`array of string`
`partial`required	`array of string`
`skipped`required	`array of string`
`truncated`required	`boolean`
`error`	`string`

401 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/repair' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Restack layers after a base changed

POST/api/v1/stacks/{id}/restack

Auth: API key

Proxies the shipped stacks control operation. Control failures retain their error and optional message/detail fields; unconfigured control returns 503, unreachable control returns 502. Bearer account owns the stack.

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackRestackResponse

One of: Option 1

Field	Type	Description
`fromBranch`required	`string`
`fromOldSha`required	`string`
`outcome`required	`EngineRestackOutcome`

400 404 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/restack' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Resume an interrupted handover between layers

POST/api/v1/stacks/{id}/resume-seam

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackResumeSeamResponse

One of: Option 1

Field	Type	Description
`seamPrNumber`required	`number`
`headSha`required	`string`
`duplicate`required	`boolean`

400 404 409 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/resume-seam' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Open or find the stack's land pull request

POST/api/v1/stacks/{id}/ensure-land-pr

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackEnsureLandPrResponse

One of: Option 1

Field	Type	Description
`landPrNumber`required	`number`
`created`required	`boolean`
`unitId`required	`string`
`uNumber`required	`number`

400 404 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/ensure-land-pr' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Abandon the stack's review unit without landing it

POST/api/v1/stacks/{id}/abandon-unit

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackAbandonUnitResponse

One of: Option 1

Field	Type	Description
`unitId`required	`string`
`uNumber`required	`number`
`ownedTrunk`required	`string`

400 404 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/abandon-unit' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Close a stack

POST/api/v1/stacks/{id}/close

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackCloseStackResponse

One of: Option 1

Field	Type	Description
`closed`required	`array of number`
`abandoned`required	`boolean`
`deleted`required	`boolean`

400 404 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/close' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Park upper layers on a frozen base

POST/api/v1/stacks/{id}/ensure-upper-park

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackEnsureUpperParkResponse

One of: Option 1

Field	Type	Description
`freezeBranch`required	`string`
`created`required	`boolean`

400 404 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/ensure-upper-park' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Sync a stack with GitHub

POST/api/v1/stacks/{id}/sync

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackSyncResponse

One of: Option 1

Field	Type	Description
`stack`required	`null \| EngineStackRecord`
`chain`required	`array of EngineStackLayer`
`deleted`required	`boolean`
`repair`required	`StackDisplayRepairResult`
`agentHeal`	`object`
`agentHeal.clearedPostedFindingKey`required	`number`
`agentHeal.clearedAwaitingFixVerdict`required	`number`
`agentHeal.clearedPendingPost`required	`number`

400 404 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/sync' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Merge queue

Queue a stack for verified landing, read the queue, land or promote the next layer, and cancel an entry.

Read merge queue entries

GET/api/v1/stacks/queue

Auth: API key

Parameters

Name	In	Type	Description
`stackId`	query	`string`	A UUID scopes entries; invalid UUID is treated as no filter.
`wait`	query	`integer`	Long poll timeout in seconds.default 0 · min 0 · max 45
`seen`	query	`string`	Previous fingerprint; unchanged or empty entries wait for an event.
`landed`	query	`"1"`	With a valid stackId, include the latest landed entry or null.

Responses

200 Successful response.

StackQueue

Field	Type	Description
`entries`required	`array of MergeQueueEntryDto`
`fingerprint`required	`string`	pattern ^[0-9a-f]{32}$
`landed`	`null \| MergeQueueEntryDto`

400 401 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/stacks/queue' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Add a stack to the merge queue

POST/api/v1/stacks/{id}/enqueue

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Responses

200 Successful response.

StackQueueEnqueueResponse

One of: EngineEnqueueMergeQueueEntryResult

400 404 409 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/enqueue' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Land the next layer

POST/api/v1/stacks/{id}/land-next

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Request body

StackOptionalPrRequest

Optional JSON body; absent, null or malformed JSON is treated as no selection. A numeric string is also accepted by runtime coercion. force is ignored on the bearer surface.

Field	Type	Description
`prNumber`	`integer \| null`

Responses

200 Successful response.

StackLandNextResponse

One of: Option 1

Field	Type	Description
`mergedPrNumber`required	`number`
`mergedBranch`required	`string`
`mergeHandled`required	`object`
`mergeHandled` as Option 1
`mergeHandled.handled`required	`false`
`mergeHandled.reason`required	`"not_in_stack" \| "foreign_parked_child"`
`mergeHandled` as Option 2
`mergeHandled.handled`required	`true`
`mergeHandled.outcome`required	`EngineRestackOutcome`

One of: Option 2

Field	Type	Description
`seamPrNumber`	`number`
`seamEnqueued`	`boolean`
`mergedPrNumber`required	`number`
`mergedBranch`required	`string`
`unitId`required	`string`
`uNumber`required	`number`
`promotedHeadSha`required	`string`
`mergeHandled`required	`object`
`mergeHandled` as Option 1
`mergeHandled.handled`required	`false`
`mergeHandled.reason`required	`"not_in_stack" \| "foreign_parked_child"`
`mergeHandled` as Option 2
`mergeHandled.handled`required	`true`
`mergeHandled.outcome`required	`EngineRestackOutcome`

400 404 409 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/land-next' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Promote the next layer into the review unit

POST/api/v1/stacks/{id}/promote-next

Auth: API key

Parameters

Name	In	Type	Description
`id`required	path	`string`

Request body

StackOptionalPrRequest

Optional JSON body; absent, null or malformed JSON is treated as no selection. A numeric string is also accepted by runtime coercion. force is ignored on the bearer surface.

Field	Type	Description
`prNumber`	`integer \| null`

Responses

200 Successful response.

StackPromoteNextResponse

One of: Option 1

Field	Type	Description
`seamPrNumber`	`number`
`seamEnqueued`	`boolean`
`mergedPrNumber`required	`number`
`mergedBranch`required	`string`
`unitId`required	`string`
`uNumber`required	`number`
`promotedHeadSha`required	`string`
`mergeHandled`required	`object`
`mergeHandled` as Option 1
`mergeHandled.handled`required	`false`
`mergeHandled.reason`required	`"not_in_stack" \| "foreign_parked_child"`
`mergeHandled` as Option 2
`mergeHandled.handled`required	`true`
`mergeHandled.outcome`required	`EngineRestackOutcome`

400 404 409 422 500 502 503 Control failure. error identifies the refusal; message and operation-specific handoff fields may be present.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/<id>/promote-next' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Cancel a merge queue entry

POST/api/v1/stacks/queue/{entryId}/cancel

Auth: API key

Parameters

Name	In	Type	Description
`entryId`required	path	`string`

Responses

200 Successful response.

StackQueueCancelResponse

One of: Option 1

Field	Type	Description
`entry`required	`EngineMergeQueueEntry`
`cancelRequested`required	`boolean`

One of: Option 2

Field	Type	Description
`entry`required	`EngineMergeQueueEntry`

202 Successful response.

StackQueueCancelResponse

One of: Option 1

Field	Type	Description
`entry`required	`EngineMergeQueueEntry`
`cancelRequested`required	`boolean`

One of: Option 2

Field	Type	Description
`entry`required	`EngineMergeQueueEntry`

400 404 409 500 502 503 Queue cancellation failure; already_finished includes the latest entry.
401 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/queue/<entryId>/cancel' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Pull requests and issues

Open pull requests and issues and push branches through the Mergestorm GitHub App, without a local GitHub token.

Find the open pull request for a branch

GET/api/v1/stacks/pulls

Auth: API key

Parameters

Name	In	Type
`owner`required	query	`string`
`repo`required	query	`string`
`head`required	query	`string`

Responses

200 Successful response.

StackPullLookup

Field	Type	Description
`number`required	`integer \| null`
`url`required	`string \| null`

400 401 403 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/stacks/pulls?owner=%3Cowner%3E&repo=%3Crepo%3E&head=%3Chead%3E' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Open a pull request

POST/api/v1/stacks/pulls

Auth: API key

Request body

StackPullRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`head`required	`string`
`base`required	`string`
`title`required	`string`
`body`	`string`

Responses

200 Successful response.

StackPullOpened

Field	Type	Description
`number`required	`integer`	min 1
`url`required	`string`
`created`required	`boolean`
`base`	`string`

201 Successful response.

StackPullOpened

Field	Type	Description
`number`required	`integer`	min 1
`url`required	`string`
`created`required	`boolean`
`base`	`string`

400 401 403 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/pulls' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "head": "<head>",
  "base": "<base>",
  "title": "<title>"
}'

Claim branches before opening their pull requests

POST/api/v1/stacks/pull-claims

Auth: API key

Request body

StackPullClaimRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`heads`required	`array of string`	min items 1 · max items 20

Responses

200 Successful response.

StackPullClaimResponse

Field	Type	Description
`claimed`required	`integer`
`expiresAt`required	`string`

400 401 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/pull-claims' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "heads": [
    "<heads>"
  ]
}'

Open a GitHub issue

POST/api/v1/stacks/issues

Auth: API key

Request body

StackIssueRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`title`required	`string`	max length 256
`body`	`string`	max length 60000
`labels`	`array of string`	max items 10

Responses

200 An open issue this route already made for the caller with the same title.

StackPullOpened

Field	Type	Description
`number`required	`integer`	min 1
`url`required	`string`
`created`required	`boolean`
`base`	`string`

201 The issue was created.

StackPullOpened

Field	Type	Description
`number`required	`integer`	min 1
`url`required	`string`
`created`required	`boolean`
`base`	`string`

400 401 403 413 500 502 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/issues' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "title": "<title>"
}'

Read a branch's publication status

GET/api/v1/stacks/publications

Auth: API key

Parameters

Name	In	Type
`owner`required	query	`string`
`repo`required	query	`string`
`branch`required	query	`string`

Responses

200 Successful response.

StackPublicationStatus

Field	Type	Description
`state`required	`"absent" \| "pushed" \| "opened" \| "registered"`
`owner`required	`string`
`repo`required	`string`
`branch`required	`string`
`head`required	`StackPublicationHead \| null`
`pr`required	`object \| null`
`pr` as Option 1
`pr.number`required	`integer`
`pr.url`required	`string`
`pr.base`required	`string`
`pr` as Option 2: null
`stack`required	`StackPublicationStack \| null`

400 401 403 500 502 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/stacks/publications?owner=%3Cowner%3E&repo=%3Crepo%3E&branch=%3Cbranch%3E' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Push commits to a branch and open its pull request

POST/api/v1/stacks/publications

Auth: API key

Parameters

Name	In	Type	Description
`x-mergestorm-chat-id`	header	`string (uuid)`	A Breeze chat of the caller. When the stack is registered, its pull request is linked to that chat and the chat follows the stack's landing and the pull request's Vortex reviews as background tasks. mg sends it from MERGESTORM_CHAT_ID.

Request body

StackPublicationRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`branch`required	`string`
`base`required	`object`
`base.branch`required	`string`
`base.sha`required	`string`
`expectedHead`required	`string \| null`	The head the branch must have now. Null means the branch must not exist.
`onto`required	`"base" \| "head"`	base starts the commits at base.sha; head appends them to expectedHead.
`commits`required	`array of StackPublicationCommit`	max items 20
`pr`required	`object`
`pr.title`required	`string`
`pr.body`	`string`
`autoLand`	`boolean`

Responses

200 Neither the branch nor the pull request was created by this request; the stack is registered.

StackPublication

Field	Type	Description
`state`required	`"registered"`
`owner`required	`string`
`repo`required	`string`
`branch`required	`string`
`base`required	`object`
`base.branch`required	`string`
`base.sha`required	`string`
`head`required	`StackPublicationHead`
`commits`required	`array of StackPublicationHead`
`branchCreated`required	`boolean`
`branchUpdated`required	`boolean`
`pr`required	`StackPullOpened`
`stack`required	`StackPublicationStack`

201 The branch or the pull request was created.

StackPublication

Field	Type	Description
`state`required	`"registered"`
`owner`required	`string`
`repo`required	`string`
`branch`required	`string`
`base`required	`object`
`base.branch`required	`string`
`base.sha`required	`string`
`head`required	`StackPublicationHead`
`commits`required	`array of StackPublicationHead`
`branchCreated`required	`boolean`
`branchUpdated`required	`boolean`
`pr`required	`StackPullOpened`
`stack`required	`StackPublicationStack`

400 401 403 409 413 422 500 502 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/stacks/publications' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "branch": "<branch>",
  "base": {
    "branch": "<branch>",
    "sha": "<sha>"
  },
  "expectedHead": "<expectedHead>",
  "onto": "base",
  "commits": [
    {
      "message": "<message>",
      "author": {
        "name": "<name>",
        "email": "<email>",
        "date": "<date>"
      },
      "committer": {
        "name": "<name>",
        "email": "<email>",
        "date": "<date>"
      },
      "tree": "<tree>",
      "changes": [
        {}
      ]
    }
  ],
  "pr": {
    "title": "<title>"
  }
}'

Agents

Start Vortex reviews, Cyclone fixes and builds, and Surge CI setup on a repository.

Start a Vortex review of an open pull request

POST/api/v1/agents/vortex/review

Auth: API key

Starts a Vortex review of the pull request at its current head (one standard credit). With head_sha, nothing starts unless that is still the head. With chat_id, the Breeze chat is woken with the result. A review already running at that head answers 200 with already_running. A repository without the Vortex App answers 409 vortex_not_installed with setup_gate {app, owner, repo, install_url}.

Request body

AgentPullRequestRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`pr_number`required	`integer`	min 1
`head_sha`	`string`	review only: the head the review must start at
`chat_id`	`string (uuid)`	review only: the Breeze chat to wake with the result

Responses

200 Successful response.

AgentRunResult

Field	Type	Description
`message`required	`string`	What happened, ready to show

202 Successful response.

AgentRunResult

Field	Type	Description
`message`required	`string`	What happened, ready to show

400 401 402 409 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/agents/vortex/review' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "pr_number": 1
}'

Cancel the Vortex review running on a pull request

POST/api/v1/agents/vortex/stop

Auth: API key

Starts nothing. Answers stopped false with reason not_running when no review runs.

Request body

AgentPullRequestRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`pr_number`required	`integer`	min 1
`head_sha`	`string`	review only: the head the review must start at
`chat_id`	`string (uuid)`	review only: the Breeze chat to wake with the result

Responses

200 Successful response.

AgentRunResult

Field	Type	Description
`message`required	`string`	What happened, ready to show

400 401 402 409 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/agents/vortex/stop' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>",
  "pr_number": 1
}'

Have Cyclone fix a pull request or build a new project

POST/api/v1/agents/cyclone/jobs

Auth: API key

task fix_findings, fix_ci or resolve_conflicts pushes a fix to pr_number; build builds brief into an empty repository and opens a pull request. A pull request with nothing to do (CI green, no conflicts, no open findings) is refused with 409 nothing_to_do and the reason. A repository without the Cyclone App answers 409 cyclone_not_installed with setup_gate {app, owner, repo, install_url}. With chat_id, the Breeze chat is woken with the job's result.

Request body

CycloneJobRequest

Field	Type	Description
`task`required	`"fix_findings" \| "fix_ci" \| "resolve_conflicts" \| "build"`
`owner`required	`string`
`repo`required	`string`
`pr_number`	`integer`	required unless task is buildmin 1
`failing_check`	`string`	fix_ci only: the check to fix
`brief`	`string`	build only: what to buildmax length 4000
`chat_id`	`string (uuid)`

Responses

200 Successful response.

AgentRunResult

Field	Type	Description
`message`required	`string`	What happened, ready to show

202 Successful response.

AgentRunResult

Field	Type	Description
`message`required	`string`	What happened, ready to show

400 401 402 409 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/agents/cyclone/jobs' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "task": "fix_findings",
  "owner": "<owner>",
  "repo": "<repo>"
}'

Read a Cyclone job started through the agents API

GET/api/v1/agents/cyclone/jobs/{dispatch_id}

Auth: API key

Parameters

Name	In	Type	Description
`dispatch_id`required	path	`string (uuid)`

Responses

200 Successful response.

CycloneJob

Field	Type	Description
`dispatch_id`required	`string (uuid)`
`task`	`"fix_findings" \| "fix_ci" \| "resolve_conflicts" \| "build" \| null`
`owner`	`string`
`repo`	`string`
`pr_number`	`integer \| null`
`branch`	`string \| null`
`state`required	`"queued" \| "running" \| "pushed" \| "completed" \| "failed"`
`outcome`	`string \| null`
`detail`	`string \| null`
`start_sha`	`string \| null`
`result_sha`	`string \| null`
`changed_files`	`array of string`
`queued_at`	`string (date-time)`
`started_at`	`string (date-time) \| null`
`finished_at`	`string (date-time) \| null`

400 401 404 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/agents/cyclone/jobs/00000000-0000-4000-8000-000000000000' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Serve a repository on Surge and open its Surge CI setup pull request

POST/api/v1/agents/surge/setup

Auth: API key

Serves the repository on Surge when the account does not serve it yet, then opens the pull request that points its workflow jobs at Surge runners and adds the merge queue batch trigger.

Request body

AgentRepositoryRequest

Field	Type	Description
`owner`required	`string`
`repo`required	`string`

Responses

200 Successful response.

AgentRunResult

Field	Type	Description
`message`required	`string`	What happened, ready to show

400 401 402 409 500 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/agents/surge/setup' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner": "<owner>",
  "repo": "<repo>"
}'

Memories

Read and write what Breeze remembers about the user and their repositories.

List the account's memories, newest first

GET/api/v1/memories

Auth: API key

Lists the memories of the key's own account, at most 1,000. Filters combine. Listing works with memory off, so the user can still see and delete what is stored.

Parameters

Name	In	Type	Description
`scope`	query	`MemoryScope (enum)`
`repo`	query	`string`	A repository as owner/repo.
`kind`	query	`MemoryKind (enum)`

Responses

200 Successful response.

MemoryList

Field	Type	Description
`memory_mode`required	`MemoryMode (enum)`
`items`required	`array of Memory`

400 401 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/memories' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Save one memory

POST/api/v1/memories

Auth: API key

Saves one memory for the key's own account. With repo it is a memory about that repository, otherwise about the user. A save that matches an existing memory updates it (merged true). Refused with memory_off when the effective memory mode is off: the Breeze chat's own mode when chat_id names a chat that has one, otherwise the account mode. Also refused with memory_full at 1,000 memories. Text that looks like a key, token or password is refused.

Request body

CreateMemoryRequest

Field	Type	Description
`text`required	`string`	min length 1 · max length 500
`kind`required	`MemoryKind (enum)`
`repo`	`string \| null`	A repository as owner/repo.
`chat_id`	`string (uuid) \| null`	The Breeze chat the memory comes from.

Responses

201 Saved.

MemorySaved

Field	Type	Description
`id`required	`string (uuid)`
`merged`required	`boolean`

400 401 409 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/memories' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "<text>",
  "kind": "rule"
}'

Search the account's memories by meaning

GET/api/v1/memories/search

Auth: API key

Searches the user's memories, and with repo that repository's memories too, best match first. rules holds the standing rules for repo. Nothing is returned when the effective memory mode is off. That mode is the chat's own mode when chat_id names a chat that has one, and the account mode otherwise, so an account mode of off does not block a chat set to all or on_request.

Parameters

Name	In	Type	Description
`query`required	query	`string`	min length 1 · max length 2000
`repo`	query	`string`	A repository as owner/repo.
`limit`	query	`integer`	default 20 · min 1 · max 20
`chat_id`	query	`string (uuid)`	The Breeze chat the search is for.

Responses

200 Successful response.

MemorySearch

Field	Type	Description
`memory_mode`required	`MemoryMode (enum)`
`rules`required	`array of Memory`
`items`required	`array of Memory`
`total`required	`integer`	min 0

400 401 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/memories/search?query=%3Cquery%3E' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Read the account's memory mode

GET/api/v1/memories/mode

Auth: API key

Responses

200 Successful response.

MemoryModeSetting

Field	Type	Description
`memory_mode`required	`MemoryMode (enum)`

401 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/memories/mode' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Set the account's memory mode

PUT/api/v1/memories/mode

Auth: API key

This sets the account default. A chat with its own memory mode keeps that mode, so with the account at off a chat set to all or on_request still saves and recalls. Where a chat has no override, off stops saving and recall, on_request saves only when the user asks, and all lets Breeze save on its own.

Request body

MemoryModeSetting

Field	Type	Description
`memory_mode`required	`MemoryMode (enum)`

Responses

200 Successful response.

MemoryModeSetting

Field	Type	Description
`memory_mode`required	`MemoryMode (enum)`

400 401 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X PUT 'https://api.mergestorm.ai/api/v1/memories/mode' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "memory_mode": "off"
}'

Correct one of the account's memories

PATCH/api/v1/memories/{memory_id}

Auth: API key

Parameters

Name	In	Type	Description
`memory_id`required	path	`string (uuid)`

Request body

UpdateMemoryRequest

Field	Type	Description
`text`required	`string`	min length 1 · max length 500
`kind`	`MemoryKind (enum)`

Responses

200 Updated.

MemoryUpdated

Field	Type	Description
`id`required	`string (uuid)`
`text`required	`string`
`kind`	`MemoryKind (enum)`

400 401 404 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X PATCH 'https://api.mergestorm.ai/api/v1/memories/00000000-0000-4000-8000-000000000000' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "<text>"
}'

Delete one of the account's memories

DELETE/api/v1/memories/{memory_id}

Auth: API key

Parameters

Name	In	Type	Description
`memory_id`required	path	`string (uuid)`

Responses

200 Deleted.

MemoryDeleted

Field	Type	Description
`id`required	`string (uuid)`
`deleted`required	`true`

401 404 413 503 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X DELETE 'https://api.mergestorm.ai/api/v1/memories/00000000-0000-4000-8000-000000000000' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Account

The account behind the API key.

Read the account and credits behind the API key

GET/api/v1/me

Auth: API key

Responses

200 API-key metadata and credit usage.

Account

Field	Type	Description
`key`required	`object`
`key.prefix`required	`string`
`key.name`required	`string`
`key.created_at`required	`string (date-time)`
`key.last_used_at`required	`string (date-time) \| null`
`plan_key`required	`string`
`plan_label_key`required	`string`
`resets_at`required	`string (date-time)`
`usage`required	`object`
`usage.standard`required	`object`
`usage.standard.used`required	`integer`
`usage.standard.limit`required	`integer \| null`
`usage.standard.remaining`required	`integer \| null`

401 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/me' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Settings

Account and per-repository agent settings.

Read the account's agent settings

GET/api/v1/settings

Auth: API key

Responses

200 Bearer-visible account settings (allowlist only).

AccountSettings

Field	Type	Description
`ignored_bot_logins`required	`array of string`	Bot logins; trimmed, lowercased, and trailing [bot] removed. Empty, invalid, or duplicate canonical logins are rejected. An empty array clears the list.
`vortex_bot_skip_check`required	`"none" \| "neutral"`
`vortex_findings_check`required	`"failure" \| "neutral" \| "success"`
`cyclone_patch_failure_check`required	`"failure" \| "neutral"`
`auto_review_enabled`required	`boolean`
`auto_patch_enabled`required	`boolean`
`auto_resolve_conflicts_enabled`required	`boolean`	Off by default. Setting for Cyclone to resolve merge conflicts on stack pull requests. Nothing reads it yet.
`auto_fix_ci_enabled`required	`boolean`	Off by default. Setting for Cyclone to fix failing CI on stack pull requests. Nothing reads it yet.
`cyclone_connected`required	`boolean`	Read-only. Cyclone GitHub app installed for this account.
`github_connected`required	`boolean`	Read-only. Vortex GitHub app installed for this account.
`stacks_ready`required	`boolean`	Read-only. The account has a Mergestorm Surge installation that is not suspended and has its permissions approved. Stacks, the merge queue and Auto land run only through Surge.
`vortex_show_thinking_traces`required	`boolean`
`repo_overview_enabled`required	`boolean`
`cyclone_review_unit_land_prs_enabled`required	`boolean`	Mirror of `auto_patch_enabled`; land PRs follow the account auto-patch setting.
`cyclone_skip_ci_enabled`required	`boolean`	When true (the default), Cyclone prefixes bot patch subjects with `[skip ci]`. Explicit false opts the account out.
`cyclone_patch_unverified_languages`required	`boolean`	Off by default. When false, Cyclone auto-patch commits TypeScript, Python, SQL, Swift, and recognized text and config file findings. TypeScript and Python have an owned typecheck gate, SQL is parsed as PostgreSQL, and Swift is parsed with `swiftc -parse`. When true, Cyclone also patches other languages and pushes them without a verify gate. Independent of `auto_patch_enabled`; human chat-fix dispatches bypass it.
`vortex_seam_specialist_enabled`required	`boolean`
`vortex_auto_overflow_enabled`required	`boolean`
`vortex_skip_all_clear_comments`required	`boolean`	Off by default. When true, Vortex skips the GitHub All-clear / nothing-new review body for a wave with no new actionable findings. The check run and coverage still complete; reviews with findings still post.
`auto_land_default`required	`boolean`	Account default for Auto land. Copied onto each stack once when it is opened; changing it never touches existing stacks.
`auto_land_settle_seconds`required	`integer`	Seconds Auto land waits after a stack looks ready before it queues or promotes it. Defaults to 60. A new value applies to settle clocks that start after the change; a running clock keeps the window it started with. min 15 · max 300
`merge_queue_batch_enabled`required	`boolean`	Off by default. When true, the merge queue may test several of the account's queued single-PR stacks on one CI run. A repository batches once its CI runs on `mq-batch-**` branches.
`merge_queue_batch_size`required	`integer`	The normal batch limit: the most pull requests the merge queue tests together in one batch. Defaults to 4. Read when a batch is planned. While merge queue overdrive resolves on for a repository, that repository's queue batches up to 10 regardless of this value. min 2 · max 10
`merge_queue_overdrive`required	`boolean`	Account default for merge queue overdrive, off by default. While it resolves on for a repository, that repository's merge queue batches up to 10 queued pull requests, even with batching off, and merge_queue_batch_size is kept. It stays on until turned off. A repository setting overrides it.
`merge_queue_lands_alone_paths`required	`array of string`	Account default for the merge queue path rule. A queued pull request that changes any file matching one of these patterns is never batched with other pull requests. A pattern without wildcards is a folder or file prefix (`db/migrate`); `` matches within one folder, `` across folders, `?` one character (`/.sql`), and a glob ending in `/` means that folder (`/migrations/` is `/migrations/`). At most 8 wildcards per pattern. Defaults to `/migrations/`, `db/migrate/` and `.github/workflows/**`. An empty list keeps only the built-in rule that a stack with more than one open pull request lands alone. Read when a batch is planned. max items 50

401 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/settings' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Change the account's agent settings

PATCH/api/v1/settings

Auth: API key

Request body

PatchSettingsRequest

Fail-closed typed allowlist. Unknown or read-only keys, invalid values, and empty objects are rejected with 400. Enabling auto_patch_enabled, auto_resolve_conflicts_enabled, or auto_fix_ci_enabled requires cyclone_connected (400 cyclone_not_connected). Disabling any of them always succeeds.

Field	Type	Description
`ignored_bot_logins`	`array of string`	Bot logins; trimmed, lowercased, and trailing [bot] removed. Empty, invalid, or duplicate canonical logins are rejected. An empty array clears the list.
`vortex_bot_skip_check`	`"none" \| "neutral"`
`vortex_findings_check`	`"failure" \| "neutral" \| "success"`
`cyclone_patch_failure_check`	`"failure" \| "neutral"`
`auto_review_enabled`	`boolean`
`auto_patch_enabled`	`boolean`
`auto_resolve_conflicts_enabled`	`boolean`
`auto_fix_ci_enabled`	`boolean`
`vortex_show_thinking_traces`	`boolean`
`repo_overview_enabled`	`boolean`
`cyclone_skip_ci_enabled`	`boolean`
`cyclone_patch_unverified_languages`	`boolean`
`vortex_seam_specialist_enabled`	`boolean`
`vortex_auto_overflow_enabled`	`boolean`
`vortex_skip_all_clear_comments`	`boolean`
`auto_land_default`	`boolean`
`auto_land_settle_seconds`	`integer`	Whole seconds from 15 through 300. Anything else is rejected with `400 invalid_value`.min 15 · max 300
`merge_queue_batch_enabled`	`boolean`
`merge_queue_batch_size`	`integer`	A whole number from 2 through 10. Anything else is rejected with `400 invalid_value`.min 2 · max 10
`merge_queue_lands_alone_paths`	`array of string`	The whole list, at most 50 folder prefixes or globs with no spaces; blank entries are dropped and duplicates folded. An empty list is a value. Anything else is rejected with `400 invalid_value`. max items 50
`merge_queue_overdrive`	`boolean`

Responses

200 Updated settings; same shape as GET so clients can confirm.

AccountSettings

Field	Type	Description
`ignored_bot_logins`required	`array of string`	Bot logins; trimmed, lowercased, and trailing [bot] removed. Empty, invalid, or duplicate canonical logins are rejected. An empty array clears the list.
`vortex_bot_skip_check`required	`"none" \| "neutral"`
`vortex_findings_check`required	`"failure" \| "neutral" \| "success"`
`cyclone_patch_failure_check`required	`"failure" \| "neutral"`
`auto_review_enabled`required	`boolean`
`auto_patch_enabled`required	`boolean`
`auto_resolve_conflicts_enabled`required	`boolean`	Off by default. Setting for Cyclone to resolve merge conflicts on stack pull requests. Nothing reads it yet.
`auto_fix_ci_enabled`required	`boolean`	Off by default. Setting for Cyclone to fix failing CI on stack pull requests. Nothing reads it yet.
`cyclone_connected`required	`boolean`	Read-only. Cyclone GitHub app installed for this account.
`github_connected`required	`boolean`	Read-only. Vortex GitHub app installed for this account.
`stacks_ready`required	`boolean`	Read-only. The account has a Mergestorm Surge installation that is not suspended and has its permissions approved. Stacks, the merge queue and Auto land run only through Surge.
`vortex_show_thinking_traces`required	`boolean`
`repo_overview_enabled`required	`boolean`
`cyclone_review_unit_land_prs_enabled`required	`boolean`	Mirror of `auto_patch_enabled`; land PRs follow the account auto-patch setting.
`cyclone_skip_ci_enabled`required	`boolean`	When true (the default), Cyclone prefixes bot patch subjects with `[skip ci]`. Explicit false opts the account out.
`cyclone_patch_unverified_languages`required	`boolean`	Off by default. When false, Cyclone auto-patch commits TypeScript, Python, SQL, Swift, and recognized text and config file findings. TypeScript and Python have an owned typecheck gate, SQL is parsed as PostgreSQL, and Swift is parsed with `swiftc -parse`. When true, Cyclone also patches other languages and pushes them without a verify gate. Independent of `auto_patch_enabled`; human chat-fix dispatches bypass it.
`vortex_seam_specialist_enabled`required	`boolean`
`vortex_auto_overflow_enabled`required	`boolean`
`vortex_skip_all_clear_comments`required	`boolean`	Off by default. When true, Vortex skips the GitHub All-clear / nothing-new review body for a wave with no new actionable findings. The check run and coverage still complete; reviews with findings still post.
`auto_land_default`required	`boolean`	Account default for Auto land. Copied onto each stack once when it is opened; changing it never touches existing stacks.
`auto_land_settle_seconds`required	`integer`	Seconds Auto land waits after a stack looks ready before it queues or promotes it. Defaults to 60. A new value applies to settle clocks that start after the change; a running clock keeps the window it started with. min 15 · max 300
`merge_queue_batch_enabled`required	`boolean`	Off by default. When true, the merge queue may test several of the account's queued single-PR stacks on one CI run. A repository batches once its CI runs on `mq-batch-**` branches.
`merge_queue_batch_size`required	`integer`	The normal batch limit: the most pull requests the merge queue tests together in one batch. Defaults to 4. Read when a batch is planned. While merge queue overdrive resolves on for a repository, that repository's queue batches up to 10 regardless of this value. min 2 · max 10
`merge_queue_overdrive`required	`boolean`	Account default for merge queue overdrive, off by default. While it resolves on for a repository, that repository's merge queue batches up to 10 queued pull requests, even with batching off, and merge_queue_batch_size is kept. It stays on until turned off. A repository setting overrides it.
`merge_queue_lands_alone_paths`required	`array of string`	Account default for the merge queue path rule. A queued pull request that changes any file matching one of these patterns is never batched with other pull requests. A pattern without wildcards is a folder or file prefix (`db/migrate`); `` matches within one folder, `` across folders, `?` one character (`/.sql`), and a glob ending in `/` means that folder (`/migrations/` is `/migrations/`). At most 8 wildcards per pattern. Defaults to `/migrations/`, `db/migrate/` and `.github/workflows/**`. An empty list keeps only the built-in rule that a stack with more than one open pull request lands alone. Read when a batch is planned. max items 50

400 401 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X PATCH 'https://api.mergestorm.ai/api/v1/settings' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

List per-repository settings

GET/api/v1/settings/repos

Auth: API key

Responses

200 One entry per repository connected to this account, with the repository-level value of each automation switch.

object

Field	Type	Description
`repos`required	`array of RepoAutomationSettings`

401 500 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl 'https://api.mergestorm.ai/api/v1/settings/repos' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY"

Change one repository's settings

PATCH/api/v1/settings/repos/{owner}/{repo}

Auth: API key

Parameters

Name	In	Type	Description
`owner`required	path	`string`
`repo`required	path	`string`

Request body

PatchRepoSettingsRequest

Unknown keys, invalid values, and empty objects are rejected with 400. null clears the repository value so the account setting applies again. Setting auto_patch_enabled to true requires Cyclone to be connected (400 cyclone_not_connected). merge_queue_batch_size takes a whole number from 2 through 10; merge_queue_lands_alone_paths takes a list of at most 50 path patterns, as on the account setting, and an empty list is a value.

Field	Type	Description
`auto_patch_enabled`	`boolean \| null`
`auto_review_enabled`	`boolean \| null`
`auto_land_default`	`boolean \| null`
`merge_queue_batch_enabled`	`boolean \| null`
`merge_queue_batch_size`	`integer \| null`	min 2 · max 10
`merge_queue_lands_alone_paths`	`array of string \| null`	max items 50
`merge_queue_overdrive`	`boolean \| null`

Responses

200 The stored repository settings.

RepoAutomationSettings

Repository-level settings for one connected repository. Each value is a value of its own or null. null means not set: the account setting applies. Precedence is the stack override, then the repository value, then the account setting. auto_land_default seeds new stacks in the repository; it does not change a stack that exists. The merge queue values override merge_queue_batch_enabled, merge_queue_batch_size and merge_queue_lands_alone_paths on the account for this repository; a repository path list replaces the account list as a whole.

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`auto_patch_enabled`required	`boolean \| null`
`auto_review_enabled`required	`boolean \| null`
`auto_land_default`required	`boolean \| null`
`merge_queue_batch_enabled`required	`boolean \| null`
`merge_queue_batch_size`required	`integer \| null`	min 2 · max 10
`merge_queue_lands_alone_paths`required	`array of string \| null`	max items 50
`merge_queue_overdrive`	`boolean \| null`

400 401 500 Request or server error.
404 repo_not_connected: the repository is not connected to this account. Only the account that connected a repository can change its settings.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X PATCH 'https://api.mergestorm.ai/api/v1/settings/repos/<owner>/<repo>' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

API keys

Manage API keys. These endpoints use the dashboard session cookie, not an API key.

List the account's API keys

GET/api/v1/keys

Auth: Dashboard session cookie

Responses

200 Keys without secret material.

object

Field	Type	Description
`keys`required	`array of ApiKey`

401 500 Request or server error.

Example

curl 'https://api.mergestorm.ai/api/v1/keys' \
  -H "Cookie: cra_session_v2=…"

Create an API key

POST/api/v1/keys

Auth: Dashboard session cookie + trusted Origin header

Request body

object

Field	Type	Description
`name`	`string`	max length 80

Responses

201 Key created; key is returned once.

ApiKeyCreated

Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`key_prefix`required	`string`
`created_at`required	`string (date-time)`
`key`required	`string`	Secret shown once.

400 401 403 500 Request or server error.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/keys' \
  -H "Cookie: cra_session_v2=…" \
  -H "Origin: https://mergestorm.ai" \
  -H "Content-Type: application/json" \
  -d '{}'

Revoke an API key

DELETE/api/v1/keys/{key_id}

Auth: Dashboard session cookie + trusted Origin header

Parameters

Name	In	Type	Description
`key_id`required	path	`string (uuid)`

Responses

200 Revoked.

object

Field	Type	Description
`ok`required	`true`

401 403 404 500 Request or server error.

Example

curl -X DELETE 'https://api.mergestorm.ai/api/v1/keys/00000000-0000-4000-8000-000000000000' \
  -H "Cookie: cra_session_v2=…" \
  -H "Origin: https://mergestorm.ai"

CLI sign-in

The device sign-in flow mg login uses to mint an API key after approval in the browser.

Start a CLI sign-in and get a device code

POST/api/v1/cli/device

Auth: None

Responses

200 Device and user codes.

DeviceStart

Field	Type	Description
`device_code`required	`string`
`user_code`required	`string`
`verification_uri`required	`string (uri)`
`verification_uri_complete`required	`string (uri)`
`interval`required	`integer`
`expires_in`required	`integer`

429 Per-key/IP window or account in-flight cap reached.
500 Request or server error.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/cli/device'

Look up a pending CLI sign-in code

GET/api/v1/cli/device/lookup

Auth: Dashboard session cookie

Parameters

Name	In	Type	Description
`user_code`required	query	`string`

Responses

200 Device-code state.

DeviceLookup

Field	Type	Description
`status`required	`"pending" \| "approved" \| "redeemed" \| "expired"`
`expires_at`required	`string (date-time)`
`expired`required	`boolean`

400 401 404 500 Request or server error.

Example

curl 'https://api.mergestorm.ai/api/v1/cli/device/lookup?user_code=%3Cuser_code%3E' \
  -H "Cookie: cra_session_v2=…"

Approve a CLI sign-in code

POST/api/v1/cli/device/approve

Auth: Dashboard session cookie + trusted Origin header

Request body

object

Field	Type	Description
`user_code`required	`string`

Responses

200 Approved.

object

Field	Type	Description
`ok`required	`true`

400 401 403 404 409 410 500 Request or server error.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/cli/device/approve' \
  -H "Cookie: cra_session_v2=…" \
  -H "Origin: https://mergestorm.ai" \
  -H "Content-Type: application/json" \
  -d '{
  "user_code": "<user_code>"
}'

Exchange an approved device code for an API key

POST/api/v1/cli/device/token

Auth: None

Request body

object

Field	Type	Description
`device_code`required	`string`

Responses

200 API key minted.

DeviceToken

Field	Type	Description
`api_key`required	`string`
`key_prefix`required	`string`

400 Pending, invalid, expired, already redeemed, or slow_down.
429 Per-key/IP window or account in-flight cap reached.
500 Request or server error.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/cli/device/token' \
  -H "Content-Type: application/json" \
  -d '{
  "device_code": "<device_code>"
}'

MCP

The hosted Model Context Protocol server. Its tools call the endpoints on this page with the same API key.

Send a request to the hosted MCP server

POST/api/v1/mcp

Auth: API key

Streamable HTTP transport for the Mergestorm MCP server. Send JSON-RPC messages (initialize, tools/list, tools/call) with the API key as a Bearer token. The optional X-Mergestorm-Chat-Id header links tool calls to a Breeze chat. Requests are at most 262,144 bytes and use the read rate budget.

Parameters

Name	In	Type	Description
`X-Mergestorm-Chat-Id`	header	`string`

Request body

object

A JSON-RPC 2.0 request or notification.

Field	Type	Description
`jsonrpc`required	`"2.0"`
`id`	`string \| integer`
`method`required	`string`
`params`	`object`

Responses

200 The JSON-RPC response, as JSON or as a server-sent event stream.

No JSON body.

401 413 Request or server error.
429 Per-key/IP window or account in-flight cap reached.

Example

curl -X POST 'https://api.mergestorm.ai/api/v1/mcp' \
  -H "Authorization: Bearer $MERGESTORM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "method": "<method>"
}'

Schemas

Named objects that endpoints send and return. Field types above link here.

ApiKey

ApiKey

Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`key_prefix`required	`string`
`created_at`required	`string (date-time)`
`last_used_at`required	`string (date-time) \| null`
`revoked`required	`boolean`

Credits

Credits

Field	Type	Description
`standard`required	`integer`	min 0

EngineAutoEnqueueSettle

EngineAutoEnqueueSettle

Field	Type	Description
`action`required	`"ready" \| "promote" \| "mergeability"`
`prNumber`required	`number`
`headSha`required	`string`
`startedAt`required	`string`
`windowSeconds`	`number`

EngineAutoLandWait

EngineAutoLandWait

Field	Type	Description
`reason`required	`string`
`prNumber`required	`null \| number`
`headSha`required	`null \| string`
`since`required	`string`
`attempts`required	`null \| number`
`detail`required	`null \| string`

EngineEnqueueMergeQueueEntryResult

EngineEnqueueMergeQueueEntryResult

Field	Type	Description
`entry`required	`EngineMergeQueueEntry`
`duplicate`required	`boolean`

EngineMergeQueueBounceDetail

EngineMergeQueueBounceDetail

Field	Type	Description
`kind`required	`"ci_failure" \| "ci_timeout" \| "head_moved" \| "seam_findings" \| "restack_conflict" \| "pr_draft" \| "must_consolidate" \| "merge_failed" \| "gh_error"`
`prNumber`	`number`
`headSha`	`string`
`failingCheck`	`string`
`conflictBranch`	`string`
`conflictDetail`	`string`
`conflictPaths`	`array of string`
`baseBranch`	`string`
`baseSha`	`string`
`message`	`string`
`warning`	`string`
`batch`	`object`
`batch.id`required	`string`
`batch.withPrNumbers`required	`array of number`

EngineMergeQueueEntry

EngineMergeQueueEntry

Field	Type	Description
`id`required	`string`
`userId`required	`string`
`stackId`required	`string`
`owner`required	`string`
`repo`required	`string`
`state`required	`"cancelled" \| "landed" \| "bounced" \| "queued" \| "running" \| "waiting"`
`waitReason`required	`null \| string`
`bounceReason`required	`null \| string`
`bounceDetail`required	`null \| EngineMergeQueueBounceDetail`
`enqueuedBy`required	`"human" \| "agent"`
`enqueuedVia`required	`"dashboard" \| "cli" \| "chat" \| "api" \| "mcp"`
`enqueuedAt`required	`string`
`attempts`required	`number`
`healCount`required	`number`
`claimedAt`required	`null \| string`
`heartbeatAt`required	`null \| string`
`claimedBy`required	`null \| string`
`landedPrNumbers`required	`array of number`
`verifyHeadSha`required	`null \| string`
`verifyBaseSha`required	`null \| string`
`floorHeadSha`required	`null \| string`
`batchId`	`null \| string`
`batchPosition`	`null \| number`
`batchStepTreeSha`	`null \| string`
`cancelRequestedAt`	`null \| string`
`finishedAt`required	`null \| string`

EngineRestackConflict

EngineRestackConflict

Field	Type	Description
`kind`required	`"rebase_conflict" \| "checkout_failed" \| "head_unresolved" \| "push_failed" \| "retarget_failed"`
`detail`required	`string`
`headSha`required	`string`
`attemptedAt`required	`string`
`attempts`required	`number`
`backupRef`required	`null \| string`
`from`	`object`
`from.branch`required	`string`
`from.oldSha`required	`string`
`droppedMergeCommit`	`boolean`
`branch`required	`string`
`paths`required	`array of string`
`state`required	`"needs_restack" \| "conflict"`

EngineRestackedLayer

EngineRestackedLayer

Field	Type	Description
`branch`required	`string`
`from`required	`string`
`to`required	`string`

EngineRestackOutcome

EngineRestackOutcome

Field	Type	Description
`restacked`required	`array of EngineRestackedLayer`
`skipped`required	`array of EngineSkippedLayer`
`conflict`	`EngineRestackConflict`

EngineSkippedLayer

EngineSkippedLayer

Field	Type	Description
`branch`required	`string`
`reason`required	`"already_current" \| "branch_gone"`

EngineStackLayer

EngineStackLayer

Field	Type	Description
`branch`required	`string`
`parentBranch`required	`null \| string`
`prNumber`required	`number`
`position`required	`number`

EngineStackRecord

EngineStackRecord

Field	Type	Description
`id`required	`string`
`userId`required	`string`
`owner`required	`string`
`repo`required	`string`
`trunkBranch`required	`string`
`landTarget`required	`string`
`archivedAt`	`null \| string`
`autoEnqueueWhenReady`	`boolean`
`autoEnqueueArmGeneration`	`number`
`autoEnqueueSettle`	`null \| EngineAutoEnqueueSettle`
`autoLandWait`	`null \| EngineAutoLandWait`
`autoReviewOverride`	`boolean \| null`
`autoPatchOverride`	`boolean \| null`
`autoResolveConflictsOverride`	`boolean \| null`
`autoFixCiOverride`	`boolean \| null`

Finding

Finding

Field	Type	Description
`finding_key`	`string`	Stable path + normalized-title selector for thin rechecks.pattern ^F-[0-9a-f]{12}$
`path`	`string \| null`
`line`	`integer \| null`
`severity`	`string`
`body`	`string`

FindingDismissFinding

FindingDismissFinding

Field	Type	Description
`finding_id`required	`string`
`finding_key`required	`string`
`path`required	`null \| string`
`line`required	`null \| number`
`title`required	`string`

FindingDismissGate

FindingDismissGate

Field	Type	Description
`seam`required	`null \| object`
`seam` as Option 1: null
`seam` as Option 2
`seam.state`required	`string`
`seam.reviewed_sha`required	`null \| string`
`seam.review_id`required	`null \| number`
`seam.cleared`required	`boolean`
`seam.blocking`required	`boolean`
`vortex`required	`null \| object`
`vortex` as Option 1: null
`vortex` as Option 2
`vortex.cleared`required	`boolean`
`vortex.reason`required	`null \| string`
`vortex.message`required	`string`
`other_gates`required	`"unchanged"`

Findings

Findings

Field	Type	Description
`inline`	`array of Finding`
`off_diff`	`array of Finding`
`offDiff`	`array of Finding`
`recheck_results`	`array of ReviewRecheckResult`

JobStatus

JobStatus (enum)

Values: "queued" | "in_progress" | "completed" | "failed" | "quota_exceeded"

Memory

Memory

Field	Type	Description
`id`required	`string (uuid)`
`scope`required	`MemoryScope (enum)`
`repo`required	`string \| null`
`kind`required	`MemoryKind (enum)`
`text`required	`string`
`source`required	`"breeze" \| "user" \| "github" \| null`
`source_url`required	`string \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`

Field	Type	Description
`stackId`required	`null \| string`
`state`required	`"running" \| "waiting"`
`claimedAt`required	`null \| string`
`waitReason`required	`null \| string`

MergeQueueBatchCiCheckDto

MergeQueueBatchCiCheckDto

Field	Type	Description
`name`required	`string`
`state`required	`"cancelled" \| "failed" \| "queued" \| "skipped" \| "passed" \| "running"`
`startedAt`required	`null \| string`
`completedAt`required	`null \| string`

MergeQueueBatchCiDto

MergeQueueBatchCiDto

Field	Type	Description
`sha`required	`string`
`observedAt`required	`string`
`checks`required	`array of MergeQueueBatchCiCheckDto`

MergeQueueBounceBatch

MergeQueueBounceBatch

Field	Type	Description
`id`required	`string`
`withPrNumbers`required	`array of number`

MergeQueueBounceDetail

MergeQueueBounceDetail

Field	Type	Description
`kind`required	`"ci_failure" \| "ci_timeout" \| "head_moved" \| "seam_findings" \| "restack_conflict" \| "pr_draft" \| "must_consolidate" \| "merge_failed" \| "gh_error"`
`prNumber`	`number`
`headSha`	`string`
`failingCheck`	`string`
`conflictBranch`	`string`
`conflictDetail`	`string`
`conflictPaths`	`array of string`
`baseBranch`	`string`
`baseSha`	`string`
`message`	`string`
`warning`	`string`
`batch`	`MergeQueueBounceBatch`

MergeQueueEntryBatchDto

MergeQueueEntryBatchDto

Field	Type	Description
`id`required	`string`
`position`required	`number`
`size`required	`number`
`state`required	`"landed" \| "bounced" \| "verifying" \| "landing" \| "stopped" \| "abandoned"`
`landedCount`required	`number`
`ci`	`null \| MergeQueueBatchCiDto`

MergeQueueEntryDto

MergeQueueEntryDto

Field	Type	Description
`id`required	`string`
`stackId`required	`string`
`owner`required	`string`
`repo`required	`string`
`state`required	`"cancelled" \| "landed" \| "bounced" \| "queued" \| "running" \| "waiting"`
`position`required	`number`
`waitReason`required	`null \| string`
`bounceReason`required	`null \| string`
`bounceDetail`required	`null \| MergeQueueBounceDetail`
`enqueuedBy`required	`"human" \| "agent"`
`enqueuedVia`required	`"dashboard" \| "cli" \| "chat" \| "api" \| "mcp"`
`enqueuedAt`required	`string`
`attempts`required	`number`
`landedPrNumbers`required	`array of number`
`verifyHeadSha`required	`null \| string`
`verifyBaseSha`required	`null \| string`
`cancelRequestedAt`	`null \| string`
`batch`	`null \| MergeQueueEntryBatchDto`
`ci`	`null \| MergeQueueBatchCiDto`
`finishedAt`required	`null \| string`
`claimedAt`	`null \| string`
`aheadInRepo`	`null \| MergeQueueAheadDto`
`repoQueue`	`null \| MergeQueueRepoQueueDto`

MergeQueueRepoQueueDto

MergeQueueRepoQueueDto

Field	Type	Description
`queuedAhead`required	`number`
`progressAt`required	`null \| string`

RepoAutomationSettings

RepoAutomationSettings

Field	Type	Description
`owner`required	`string`
`repo`required	`string`
`auto_patch_enabled`required	`boolean \| null`
`auto_review_enabled`required	`boolean \| null`
`auto_land_default`required	`boolean \| null`
`merge_queue_batch_enabled`required	`boolean \| null`
`merge_queue_batch_size`required	`integer \| null`	min 2 · max 10
`merge_queue_lands_alone_paths`required	`array of string \| null`	max items 50
`merge_queue_overdrive`	`boolean \| null`

RestackError

RestackError

Field	Type	Description
`kind`required	`"rebase_conflict" \| "checkout_failed" \| "head_unresolved" \| "push_failed" \| "retarget_failed"`
`detail`required	`string`
`headSha`required	`string`
`attemptedAt`required	`string`
`attempts`required	`number`
`backupRef`required	`null \| string`
`from`	`object`
`from.branch`required	`string`
`from.oldSha`required	`string`
`droppedMergeCommit`	`boolean`

ReviewDismissalClear

ReviewDismissalClear

Field	Type	Description
`reviewId`required	`number`
`headSha`required	`string`
`verdict`required	`"approve" \| "comment"`
`openWarnings`required	`number`

ReviewFile

ReviewFile

Field	Type	Description
`path`required	`string`	min length 1
`content`required	`string`	min length 1

ReviewFindingComment

ReviewFindingComment

Field	Type	Description
`path`required	`string`
`line`required	`number`
`body`required	`string`
`title`	`string`
`severity`required	`"error" \| "info" \| "warning"`
`category`	`"bug" \| "correctness" \| "error_handling" \| "race_condition" \| "security" \| "performance" \| "style_nit" \| "test" \| "docs" \| "other"`
`specialist`	`"api" \| "seam" \| "security" \| "performance" \| "architecture" \| "tests" \| "data" \| "frontend" \| "governance"`
`githubCommentId`	`number`
`carriedFromSha`	`string`
`dismissalKey`	`string`

ReviewFindings

ReviewFindings

Field	Type	Description
`summary`required	`string`
`verdict`required	`"approve" \| "request_changes" \| "comment"`
`inline`required	`array of ReviewFindingComment`
`offDiff`required	`array of ReviewFindingComment`
`patchPolicy`	`ReviewPatchPolicy`
`replaceActionable`	`boolean`
`dismissalClear`	`ReviewDismissalClear`

ReviewJobListItem

ReviewJobListItem

Field	Type	Description
`job_id`required	`string`
`thread_slug`required	`string \| null`
`thread_job_number`required	`integer \| null`
`status`required	`JobStatus (enum)`
`verdict`required	`Verdict (enum)`
`summary`required	`string \| null`
`base_label`required	`string \| null`
`head_label`required	`string \| null`
`router_mode`required	`RouterMode (enum)`
`specialists_requested`required	`array of string`
`specialists_run`required	`array of string \| null`
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`
`credits`required	`Credits`
`key_prefix`required	`string \| null`	Prefix of the API key that submitted the job. Null for cookie-only or pre-attribution jobs.

ReviewPatchPolicy

ReviewPatchPolicy

Field	Type	Description
`mode`required	`"hold" \| "apply"`
`reason`	`string`

ReviewRecheck

ReviewRecheck

Field	Type	Description
`request`required	`object`
`results`required	`array of ReviewRecheckResult \| null`

ReviewRecheckRequest

object

Field	Type	Description
`finding_keys`required	`array of string`	max items 40
`paths`required	`array of string`	max items 40
`specialists`required	`array of Specialist (enum)`	max items 5

ReviewRecheckResult

ReviewRecheckResult

Field	Type	Description
`finding_key`required	`string`	pattern ^F-[0-9a-f]{12}$
`status`required	`"fixed" \| "still_open" \| "not_in_diff" \| "not_reviewed"`

Field	Type	Description
`agent`required	`"vortex" \| "cyclone"`
`status`required	`string`
`sha`required	`null \| string`
`pass`	`null \| number`
`skipReason`	`null \| string`
`startedAt`	`null \| string`
`finishedAt`	`null \| string`
`phase`	`null \| string`
`findingCount`	`null \| number`
`coverage`	`null \| object`
`coverage` as Option 1: null
`coverage` as Option 2
`coverage.reviewed`required	`number`
`coverage.total`required	`number`
`detail`	`null \| string`

StackAgentsBusy

StackAgentsBusy

Field	Type	Description
`vortex`required	`boolean`
`cyclone`required	`boolean`
`headSha`required	`null \| string`

StackCycloneHandoff

StackCycloneHandoff

Field	Type	Description
`headSha`required	`string`
`reason`required	`string`
`at`required	`null \| string`
`detail`	`null \| string`

StackDisplayRepairResult

StackDisplayRepairResult

Field	Type	Description
`outcome`required	`"failed" \| "skipped" \| "complete" \| "partial"`
`stacks`required	`array of StackDto`
`repaired`required	`array of string`
`partial`required	`array of string`
`skipped`required	`array of string`
`truncated`required	`boolean`
`error`	`string`

StackDto

StackDto

Field	Type	Description
`id`required	`string`
`owner`required	`string`
`repo`required	`string`
`trunkBranch`required	`string`
`landTarget`required	`string`
`archivedAt`required	`null \| string`
`autoEnqueueWhenReady`	`boolean`
`autoLandOff`	`null \| object`
`autoLandOff` as Option 1: null
`autoLandOff` as Option 2
`autoLandOff.reason`required	`"user" \| "archive" \| "watcher" \| "cancelled" \| "landed" \| "bounced"`
`autoLandOff.entryId`required	`null \| string`
`autoLandOff.at`required	`string`
`autoEnqueueSettle`	`null \| object`
`autoEnqueueSettle` as Option 1: null
`autoEnqueueSettle` as Option 2
`autoEnqueueSettle.action`required	`"ready" \| "promote" \| "mergeability"`
`autoEnqueueSettle.prNumber`required	`number`
`autoEnqueueSettle.headSha`required	`string`
`autoEnqueueSettle.startedAt`required	`string`
`autoEnqueueSettle.windowSeconds`	`number`
`autoLandWait`	`null \| object`
`autoLandWait` as Option 1: null
`autoLandWait` as Option 2
`autoLandWait.reason`required	`string`
`autoLandWait.prNumber`required	`null \| number`
`autoLandWait.headSha`required	`null \| string`
`autoLandWait.since`required	`string`
`autoLandWait.attempts`required	`null \| number`
`autoLandWait.detail`required	`null \| string`
`autoReviewOverride`	`boolean \| null`
`autoPatchOverride`	`boolean \| null`
`autoResolveConflictsOverride`	`boolean \| null`
`autoFixCiOverride`	`boolean \| null`
`keyUserId`	`string`
`cycloneInstallUserId`	`null \| string`
`cycloneOwnerMatch`	`"same" \| "different" \| "none" \| "lookup_failed"`
`cyclonePatchOff`	`"stack_auto_patch_off" \| "repo_auto_patch_off" \| "repo_setting_unavailable" \| "account_auto_patch_off" \| "cyclone_not_connected"`
`vortexReviewOff`	`"stack_auto_review_off" \| "repo_auto_review_off" \| "account_auto_review_off"`
`cycloneConflictOff`	`"cyclone_not_connected" \| "stack_auto_resolve_off" \| "account_auto_resolve_off"`
`cycloneCiOff`	`"cyclone_not_connected" \| "stack_auto_fix_ci_off" \| "account_auto_fix_ci_off"`
`infrastructureInstallUserId`	`null \| string`
`infrastructureOwnerMatch`	`"same" \| "different" \| "none" \| "lookup_failed"`
`layers`required	`array of StackLayerDto`
`unit`	`StackUnitDto`

StackLayerChecks

StackLayerChecks

Field	Type	Description
`total`required	`number`
`success`required	`number`
`pending`required	`number`
`failure`required	`number`
`failingName`required	`null \| string`
`selfHosted`	`number`
`namedRunsSeeded`	`boolean`
`cancelledOnly`	`boolean`
`namedRunsCompleteHeadSha`	`string`
`combinedStatusSeeded`	`boolean`

StackLayerCiFix

StackLayerCiFix

Field	Type	Description
`status`required	`"failed" \| "held" \| "verified" \| "unverified" \| "no_changes"`
`failingCheck`required	`null \| string`
`resultSha`required	`null \| string`
`reason`required	`null \| string`
`at`required	`string`
`checkOnResult`	`"pending" \| "failed" \| "passed" \| "did_not_run"`

StackLayerConflictResolution

StackLayerConflictResolution

Field	Type	Description
`resolvedAt`required	`string`
`baseBranch`required	`null \| string`
`files`required	`array of string`
`headSha`required	`null \| string`
`dispatchId`required	`null \| string`

StackLayerDto

StackLayerDto

Field	Type	Description
`branch`required	`string`
`parentBranch`required	`null \| string`
`prNumber`required	`number`
`openedAt`required	`null \| string`
`mergedAt`required	`null \| string`
`closedAt`required	`null \| string`
`additions`required	`null \| number`
`deletions`required	`null \| number`
`openAdditions`required	`null \| number`
`openDeletions`required	`null \| number`
`position`required	`number`
`state`required	`"clean" \| "needs_restack" \| "restacking" \| "conflict" \| "merged" \| "closed"`
`title`required	`null \| string`
`htmlUrl`required	`null \| string`
`ciStatus`required	`"none" \| "success" \| "pending" \| "failure" \| "neutral" \| "unknown"`
`reviewStatus`required	`"none" \| "unknown" \| "approved" \| "changes_requested" \| "reviewed" \| "failed"`
`checks`required	`null \| StackLayerChecks`
`vortexStatus`required	`null \| "failed" \| "queued" \| "skipped" \| "reviewing" \| "seam_pending" \| "all_clear" \| "findings" \| "throttled" \| "incomplete"`
`cycloneStatus`required	`null \| "failed" \| "patching" \| "awaiting_fix" \| "held"`
`agentRuns`	`array of StackAgentRun`
`vortexReview`	`StackVortexReviewView`
`agentsBusy`	`null \| StackAgentsBusy`
`cycloneHandoff`	`null \| StackCycloneHandoff`
`cycloneConflictHandoff`	`null \| StackCycloneHandoff`
`cycloneConflictPendingSince`	`null \| string`
`cycloneCiHandoff`	`null \| StackCycloneHandoff`
`cycloneCiPendingSince`	`null \| string`
`cycloneFindingsTakenAtHead`	`boolean`
`conflictDetail`required	`null \| string`
`restackError`	`null \| RestackError`
`lastRestackedSha`required	`null \| string`
`mergeable`required	`boolean \| null`
`mergeableState`required	`null \| string`
`headSha`	`null \| string`
`mergeableHeadSha`	`null \| string`
`draft`	`boolean \| null`
`linkedIssues`	`null \| array of StackLinkedIssue`
`specialistsRun`	`null \| array of string`
`specialistRunCounts`	`null \| map of number`
`coreRuns`	`null \| number`
`conflictResolution`	`null \| StackLayerConflictResolution`
`ciFix`	`null \| StackLayerCiFix`

StackLinkedIssue

StackLinkedIssue

Field	Type	Description
`number`required	`number`
`title`required	`null \| string`

StackPublicationChange

StackPublicationChange

One of: Option 1

Field	Type	Description
`path`required	`string`
`deleted`required	`true`

One of: Option 2

Field	Type	Description
`path`required	`string`
`deleted`	`false`
`mode`required	`"100644" \| "100755" \| "120000"`
`sha`required	`string`	Git blob SHA of the content.
`content`required	`string`	The whole file, base64. A symlink carries its target path.

StackPublicationCommit

StackPublicationCommit

Field	Type	Description
`message`required	`string`
`author`required	`StackPublicationIdentity`
`committer`required	`StackPublicationIdentity`
`tree`required	`string`	Git tree SHA of this commit. The branch moves only when GitHub builds the same tree.
`changes`required	`array of StackPublicationChange`	Every path that differs from the commit before it. A rename is a deletion and an addition.

StackPublicationHead

StackPublicationHead

Field	Type	Description
`sha`required	`string`
`tree`required	`string \| null`

StackPublicationIdentity

StackPublicationIdentity

Field	Type	Description
`name`required	`string`
`email`required	`string`
`date`required	`string`	ISO 8601 with seconds and a UTC offset, for example 2026-10-11T15:03:00-04:00.

StackPublicationStack

StackPublicationStack

Field	Type	Description
`id`required	`string`
`autoPatchOverride`required	`boolean \| null`
`autoLand`required	`boolean`

StackPullOpened

StackPullOpened

Field	Type	Description
`number`required	`integer`	min 1
`url`required	`string`
`created`required	`boolean`
`base`	`string`

StackUnitDto

StackUnitDto

Field	Type	Description
`id`required	`string`
`uNumber`required	`number`
`state`required	`string`
`branch`required	`string`
`landTarget`required	`string`
`members`required	`array of StackUnitMemberDto`
`landPrNumber`required	`null \| number`
`landingBlockReason`required	`null \| string`
`landPr`required	`null \| StackLayerDto`

StackUnitMemberDto

StackUnitMemberDto

Field	Type	Description
`prNumber`required	`number`
`openedAt`required	`null \| string`
`mergedAt`required	`null \| string`
`closedAt`required	`null \| string`
`additions`required	`null \| number`
`deletions`required	`null \| number`
`openAdditions`required	`null \| number`
`openDeletions`required	`null \| number`
`branch`required	`string`
`position`required	`number`
`seamState`required	`string`
`seamReviewedSha`required	`null \| string`
`promotedHeadSha`required	`null \| string`
`promotedAt`required	`string`
`title`	`null \| string`
`linkedIssues`	`null \| array of StackLinkedIssue`
`specialistsRun`	`null \| array of string`
`specialistRunCounts`	`null \| map of number`
`coreRuns`	`null \| number`

StackVortexReviewView

StackVortexReviewView

Field	Type	Description
`status`required	`"none" \| "failed" \| "queued" \| "skipped" \| "reviewing" \| "done"`
`skip_reason`required	`null \| string`
`pass`required	`null \| number`
`head_sha`required	`null \| string`
`phase`required	`null \| string`
`started_at`required	`null \| string`
`settled_at`	`null \| string`
`stoppable`required	`boolean`
`source`required	`"none" \| "pr_reviews" \| "github_webhook_jobs" \| "lease"`

ThreadJob

ThreadJob

Field	Type	Description
`job_id`required	`string`
`status`required	`JobStatus (enum)`
`summary`required	`string \| null`
`verdict`required	`Verdict (enum)`
`thread_job_number`required	`integer \| null`
`created_at`required	`string (date-time)`
`finished_at`required	`string (date-time) \| null`

ThreadListItem

ThreadListItem

Field	Type	Description
`slug`required	`string`
`branch`required	`string \| null`
`owner`required	`string \| null`
`repo`required	`string \| null`
`pr_number`required	`integer \| null`
`status`required	`string`
`job_count`required	`integer`
`last_verdict`required	`Verdict (enum)`
`last_activity_at`required	`string (date-time)`

Verdict

Verdict (enum)

Values: "approve" | "comment" | "request_changes" | null