---
title: "Put a test in a state"
method: POST
path: "/ci/{owner}/repositories/{repository}/test-states"
tags: ["test_insights"]
---

# Put a test in a state

`POST /ci/{owner}/repositories/{repository}/test-states`

## Request

- Base URL: `https://api.mergify.com/v1`
- URL: `https://api.mergify.com/v1/ci/{owner}/repositories/{repository}/test-states`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

Put a test in a state for a branch, pipeline and job.

## Path parameters

- `repository` string, required: The name of the repository
- `owner` string, required: The owner of the repository

## Request body

- CreateTestStatePayload
  - `state` 'quarantined', required
  - `test_name` string, required: The fully qualified name of the test.
  - `reason` string, required: Why the test is put in this state.
  - `issue_url` string, nullable: Link to where the fix of the test is tracked, such as an issue in your issue tracker. Must be an `http` or `https` URL.
  - `branch_name` string, nullable: Branch the state applies to. Every branch when not specified.
  - `pipeline_name` string, nullable: Pipeline the state applies to. Every pipeline when not specified.
  - `job_name` string, nullable: Job the state applies to. Every job when not specified.
  - `unquarantine_when_healthy` boolean: For the `quarantined` state: unquarantine the test once it recovers, when Mergify no longer detects it as flaky or broken.

## Response `201`

Successful Response

- TestStateCreatedResponse
  - `id` string, uuid, required: The ID of the created test state.

## Other responses

- `403`: Forbidden
- `404`: Not found
- `409`: `TEST_STATE_OVERLAP`: The test already has a state applying to some of the same runs.
- `422`: Unprocessable entity

## Changes

- **2026-10-22** `f0fe01773ba8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mergify/apis/mergify-api/changes/ci/:owner/repositories/:repository/test-states/post.md)

---

[API](https://skmtc.dev/mergify/apis/mergify-api.md) · [All operations](https://skmtc.dev/mergify/apis/mergify-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mergify/apis/mergify-api/revisions/00b8f4a31190?raw)