Test case review settings API

Each project has test case review settings: whether changes to its test cases go through a review before they reach the repository, and how that review works. They are the API side of the Repository tab in project settings.

Test case review is included in the Pro and Enterprise plans (and available during a trial). On other plans both endpoints, and their MCP tools, answer 403 forbidden; GET /api/v1/orgs/current carries caseReviewEnabled so you can check first. A downgrade keeps the stored settings.

{projectId} is the project code (for example ACME).

Settings

Key	Type	Default	Meaning
enabled	boolean	false	Test case review is on for the project. While false, the other settings are stored but have no effect.
mandatory	boolean	false	Every new case and every change to a case must be sent for review.
allowSelfMerge	boolean	false	The author of a review request can merge it.
approvalsRequired	integer >= 0	1	Approvals a request needs before it can be merged. 0 means no threshold.
autoMerge	boolean	false	Merge a request as soon as it reaches approvalsRequired. Needs approvalsRequired of at least 1.
onlyApprovedInRuns	boolean	false	Only test cases whose reviewStatus is approved can be added to runs. See Run cases.
defaultReviewerUserIds	array of member ULID	[]	Members assigned to every new review request, in the order given. At most 50.

Get review settings

GET /api/v1/projects/{projectId}/review-settings

Open to anyone who can read the project.

{
  "enabled": true,
  "mandatory": false,
  "allowSelfMerge": false,
  "approvalsRequired": 1,
  "autoMerge": false,
  "onlyApprovedInRuns": false,
  "defaultReviewerUserIds": ["01J8Z3W4X5Y6Z7A8B9C0D1E2F3"]
}

A default reviewer who has left the organization or lost access to the project is not listed. The reviewer is listed again if their access comes back.

Update review settings

PATCH /api/v1/projects/{projectId}/review-settings

Send only the keys you want to change; at least one is required, and an unknown key is rejected. The response is the full settings object, as GET returns it.

{
  "enabled": true,
  "mandatory": true,
  "approvalsRequired": 2,
  "defaultReviewerUserIds": ["01J8Z3W4X5Y6Z7A8B9C0D1E2F3"]
}

• defaultReviewerUserIds replaces the whole list; [] clears it. Every ULID must name a current member of the organization with access to the project whose role holds the test-cases.review permission, otherwise the request answers 422 validation_failed, details.defaultReviewerUserIds lists the ULIDs that were refused, and nothing is saved.
• autoMerge: true needs approvalsRequired of at least 1. The rule is checked against the stored settings too: turning on autoMerge while the stored count is 0, or lowering the count to 0 while autoMerge is on, answers 422 validation_failed and saves nothing.
• A change records one project.review_settings_updated audit event whose metadata.changes names each changed setting with its previous and new value. For defaultReviewers, the values are the number of reviewers. A request that changes nothing records no event.

Authorization

Requires the projects.manage permission (held by organization owners and admins today), or being the project’s current owner, like the test-run settings. Anyone else receives 403 forbidden. Archived projects keep their settings editable.

Errors

Status	Code	When
403	forbidden	The plan does not include test case review, or the caller cannot change the settings.
404	not_found	No project with that code in your organization, or you cannot read it.
422	validation_failed	Unknown key, empty body, invalid value, auto-merge without a required approval, or an ineligible default reviewer.

MCP tools

get_project_review_settings and update_project_review_settings take project_id and the same keys. See the MCP tool reference.