# Test case review settings API

> Read and change a project's test case review settings — whether review is on, mandatory, self-merge, approvals required, auto-merge and default reviewers.

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](https://docs.probara.net/en/developers/api/run-cases/#only-approved-cases). |
| `defaultReviewerUserIds` | array of member ULID | `[]`    | Members assigned to every new review request, in the order given. At most 50.                                                                |

## Get review settings

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

Open to anyone who can read the project.

```json
{
  "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

```http
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.

```json
{
  "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](https://docs.probara.net/en/developers/api/project-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](https://docs.probara.net/en/developers/mcp-tools/).