---
title: "Edit a detector"
method: PATCH
path: "/api/v1/public/detectors/{detector_id}"
tags: ["Detectors"]
---

# Edit a detector

`PATCH /api/v1/public/detectors/{detector_id}`

## Request

- Base URL: `https://app.traceroot.ai`
- URL: `https://app.traceroot.ai/api/v1/public/detectors/{detector_id}`
- Auth: HTTP bearer

Edit a detector in a project the authenticated user can write to.

Requires MEMBER role or higher in the project's workspace (the write
service decides). Only the sent fields change; ``template`` is immutable.

Args:
    request (Request): Incoming request (rate-limit plumbing).
    response (Response): Outgoing response (rate-limit plumbing).
    auth (AccountStampedAuth): Account-scope user auth (session token or
        CLI access JWT); its resolved ``user_id`` becomes the actor.
    detector_id (str): The detector to edit.
    payload (UpdateDetectorRequest): The project and the fields to change.
    _live (None): Write-path liveness gate (blocks a revoked JWT session).

Returns:
    UpdateDetectorResponse: The updated detector and the changed fields.

Raises:
    HTTPException: The write service's 400/403/404/409 verbatim, or a
        503 when its response is ambiguous.

## Path parameters

- `detector_id` string, required

## Request body

- UpdateDetectorRequest: Body for editing a detector; ``template`` is immutable and not accepted.
  - `detection_model` string, nullable
  - `detection_provider` string, nullable
  - `detection_source` 'system' | 'byok', nullable
  - `enable_rca` boolean
  - `enabled` boolean: The pause switch. Detection is ingestion-triggered, so enabling starts nothing retroactively.
  - `name` string
  - `output_schema` unknown[]: Replaces the whole output schema array
    - unknown
  - `project_id` string, required
  - `prompt` string: Detector instructions, stored verbatim. There is no reset to a template's default on update: send the canonical text to restore it.
  - `sample_rate` integer
  - `trigger_conditions` unknown[]: Replaces the whole trigger array; [] removes the trigger so every completed trace is evaluated. Each condition is {field, op, value} (metadata also takes key): model_name/environment take =, !=; cost/total_tokens/duration_ms/errors take >, >=, <, <=, =; metadata takes =, contains.
    - unknown

## Response `200`

Successful Response

- UpdateDetectorResponse: The updated detector.
  - `changed` string[], required
  - `detector` DetectorRow, required: A detector as the write service returns it.
    - `enabled` boolean, required
    - `id` string, required
    - `name` string, required
    - `project_id` string, required
    - `sample_rate` integer, required
  - `updated` boolean, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed or session revoked
- `403`: Insufficient role or wrong credential kind
- `404`: Not found
- `409`: Name already in use
- `422`: Validation Error
- `503`: Write service unavailable

---

[API](https://skmtc.dev/traceroot/apis/traceroot-public-api.md) - [All operations](https://skmtc.dev/traceroot/apis/traceroot-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/traceroot/apis/traceroot-public-api/revisions/ce6aef96c0d6?raw)