Skip to main content

Case Merge & Split

Split a case into two cases or merge two cases into one when automatic grouping needs adjustment. Both restructuring operations survive case rebuilds.

When the automatic case grouping does not match your needs, split a case into two partitions or merge two cases together.

These operations let you manually adjust case boundaries. Splitting moves the partition_b documents out into a new case (everything else stays). Merging absorbs one case into another. Both survive rebuilds: split marks the moved documents removed on the source and pinned on the new case; merge tombstones the absorbed case so a recompute never resurrects it.

When merging, case_key_b (a case UUID) is absorbed into case_key_a: its documents, links, and findings are reparented onto A and A survives. The absorbed case is tombstoned (merged_into = A) and excluded from future rebuilds — it is not deleted.
POST/v1/cases/:key/split

Body parameters

partition_b*string[]Document IDs that move out into a new case. Must be a non-empty strict subset of the case; everything not listed stays on the existing case.
partition_astring[]Informational only — the documents kept on the existing case are derived as the complement of partition_b.

Response

Response fields

source_idstringUUID of the existing case (retains the partition_a documents).
new_case_idstringUUID of the newly created case holding the partition_b documents.
movednumberCount of documents moved into the new case.

Response

{
  "source_id": "5c7fa78c-4d92-4613-9f42-9fe74458d8a9",
  "new_case_id": "9d1f2a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "moved": 3
}
POST/v1/cases/merge

Body parameters

case_key_a*stringUUID of the surviving target case — receives the merged documents.
case_key_b*stringUUID of the absorbed case — its documents, links, and findings are reparented onto case A and it is tombstoned.

Response

Response fields

idstringUUID of the surviving (target) case.
case_keystringContent-derived key of the surviving case (hex).
statusstringLifecycle status of the surviving case (unchanged by the merge).
display_namestring | nullUser-curated name of the surviving case, if set.

The response is the surviving target case row — it also carries assignee, resolution_notes, title, blurb, summary, source, stale, and build timestamps.

Response

{
  "id": "5c7fa78c-4d92-4613-9f42-9fe74458d8a9",
  "case_key": "8c1ca050535e3ea3",
  "status": "discovered",
  "display_name": "Acme onboarding",
  "assignee": null,
  "stale": false
}

Errors

Error responses

400bad_requestInvalid case key format.
401unauthorizedMissing or invalid API key.
404not_foundOne or both cases not found.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

What happens to findings when cases are merged?+
Open findings from the absorbed case are reparented onto the surviving case, keeping their dismissed/severity state.
Do I need to include every document when splitting?+
No. Only partition_b (the documents that move out) is required — it must be a non-empty strict subset of the case. Everything not listed stays on the existing case; partition_a is informational.
Can I merge more than two cases at once?+
No. The merge endpoint accepts exactly two case UUIDs. To merge multiple cases, chain merge calls — merge A and B first, then merge the result with C.

Related

List Cases
Case Operations