---
title: "Signal Patch"
method: PATCH
path: "/api/orgs/{orgHandle}/projects/{projectHandle}/signals/{signalId}"
tags: ["Signals"]
---

# Signal Patch

`PATCH /api/orgs/{orgHandle}/projects/{projectHandle}/signals/{signalId}`

## Request

- Base URL: `https://mcp.usertold.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://mcp.usertold.ai/api/orgs/{orgHandle}/projects/{projectHandle}/signals/{signalId}`
- Auth: none declared

Execute the UserTold signal patch operation.

## Path parameters

- `orgHandle` string, required: orgHandle path parameter
- `projectHandle` string, required: projectHandle path parameter
- `signalId` string, required: signalId path parameter

## Request body

- object
  - `signal_type` string
  - `target_surface` 'product_under_test' | 'usertold_widget_interview' | 'interviewer_conductor_behavior' | 'ambiguous_needs_review' | 'null', nullable
  - `confidence` number
  - `intensity` number, nullable
  - `quote` string
  - `timestamp_ms` number, nullable
  - `page_url` string, nullable
  - `page_title` string, nullable
  - `preceding_actions` string[], nullable
  - `user_goal` string, nullable
  - `outcome` string, nullable
  - `headline` string, nullable
  - `claim` string, nullable
  - `reconstruction` string, nullable
  - `observed_facts` string[], nullable

## Response `200`

Success

- ApiSignalResponse
  - `signal` object, required
    - `id` string, required
    - `project_ref` string, required
    - `session_id` string, required
    - `signal_type` string, required
    - `target_surface` 'product_under_test' | 'usertold_widget_interview' | 'interviewer_conductor_behavior' | 'ambiguous_needs_review', required
    - `confidence` number, required
    - `intensity` number, nullable, required
    - `quote` string, required
    - `timestamp_ms` number, nullable, required
    - `segment_id` string, nullable, required
    - `page_url` string, nullable, required
    - `page_title` string, nullable, required
    - `preceding_actions` string, nullable, required
    - `user_goal` string, nullable, required
    - `outcome` string, nullable, required
    - `headline` string, nullable
    - `claim` string, nullable
    - `reconstruction` string, nullable
    - `observed_facts_json` string, nullable
    - `evidence_grade` string, nullable
    - `window_start_ms` number, nullable
    - `window_end_ms` number, nullable
    - `transcript_uncertain` boolean, required
    - `transcript_uncertainty_note` string, nullable, required
    - `review_status` string, nullable
    - `review_note` string, nullable
    - `annotation_text` string, nullable, required
    - `annotation_by` string, nullable, required
    - `annotation_at` string, nullable, required
    - `dismissed_at` string, nullable, required
    - `dismissed_reason` string, nullable, required
    - `dismissed_by` string, nullable, required
    - `source` string, nullable, required
    - `created_at` string, required
    - `linked_task` object, nullable
      - `id` string, required
      - `title` string, required
      - `status` 'backlog' | 'ready' | 'in_progress' | 'done' | 'wont_fix', required
      - `linear_issue_id` string, nullable
      - `linear_issue_url` string, nullable
      - `linear_issue_status` string, nullable
    - `evidence_resolution` object, nullable
      - `link_id` string, required
      - `task_id` string
      - `linked_at` string, nullable, required
      - `resolved_at` string, nullable, required
      - `resolved_by_provider` string, nullable, required
      - `resolved_by_provider_issue_id` string, nullable, required
      - `resolution_reason` string, nullable, required
    - `recurrence_candidates` object[]
      - `id` string, required
      - `related_task_id` string, required
      - `related_resolved_signal_id` string, nullable, required
      - `confidence` number, required
      - `reason` string, nullable, required
      - `status` 'candidate' | 'confirmed' | 'dismissed', required
      - `created_at` string, required
      - `reviewed_at` string, nullable, required
      - `related_task` object, nullable
        - `id` string, required
        - `title` string, required
        - `status` 'backlog' | 'ready' | 'in_progress' | 'done' | 'wont_fix', required
    - `provenance` object, nullable
      - `study` object, nullable, required
        - `ref` string, required
        - `handle` string, required
        - `title` string, required
      - `interview` object, nullable, required
        - `id` string, required
        - `participant_name` string, nullable, required
        - `started_at` string, nullable, required
        - `interview_mode` string, nullable, required
        - `duration_seconds` number, nullable, required
      - `page` object, nullable, required
        - `url` string, nullable, required
        - `title` string, nullable, required
      - `timestamp_ms` number, nullable, required
      - `source` string, nullable, required
    - `case_file` object, nullable
      - `case_file_version` 'evidence_case_file.v1', required
      - `evidence_card` object, required
        - `contract_version` 'pipeline.v1', required
        - `artifact_kind` 'evidence_card', required
        - `artifact_id` string
        - `session_id` string
        - `created_at` string
        - `evidence` object, required
          - `signal_type` 'struggling_moment' | 'desired_outcome' | 'workaround' | 'hiring_criteria' | 'firing_moment' | 'emotional_response' | 'no_issue_found' | 'smooth_completion' | 'critical_error' | 'recovery_success' | 'decision_point', required
          - `target_surface` 'product_under_test' | 'usertold_widget_interview' | 'interviewer_conductor_behavior' | 'ambiguous_needs_review', required
          - `headline` string
          - `quote` string, required
          - `observed_facts` string[]
          - `claim` string
          - `reconstruction` string
          - `evidence_grade` 'direct' | 'strong_circumstantial' | 'weak', required
          - `confidence` number, required
          - `intensity` number, nullable
          - `timestamp_ms` number
          - `window_start_ms` number
          - `window_end_ms` number
          - `segment_id` string
          - `page_url` string, nullable
          - `page_title` string, nullable
          - `preceding_actions` string[], nullable
          - `user_goal` string, nullable
          - `outcome` string, nullable
          - `transcript_uncertain` boolean, required
          - `transcript_uncertainty_note` string, nullable
        - `project_ref` string
      - `provenance` object, nullable, required
        - `study` object, nullable, required
          - `handle` string, required
          - `title` string, required
        - `interview` object, nullable, required
          - `id` string, required
          - `participant_name` string, nullable, required
          - `started_at` string, nullable, required
          - `interview_mode` string, nullable, required
          - `duration_seconds` number, nullable, required
        - `page` object, nullable, required
          - `url` string, nullable, required
          - `title` string, nullable, required
        - `timestamp_ms` number, nullable, required
        - `source` string, nullable, required
      - `review` object, required
        - `review_status` string, nullable, required
        - `review_note` string, nullable, required
        - `annotation_text` string, nullable, required
        - `annotation_by` string, nullable, required
        - `annotation_at` string, nullable, required
        - `dismissed_at` string, nullable, required
        - `dismissed_reason` string, nullable, required
        - `dismissed_by` string, nullable, required
      - `links` object, required
        - `linked_task` object, nullable
          - `id` string, required
          - `title` string, required
          - `status` string, required
          - `linear_issue_id` string, nullable
          - `linear_issue_url` string, nullable
          - `linear_issue_status` string, nullable
        - `evidence_resolution` object, nullable
          - `link_id` string, required
          - `task_id` string
          - `linked_at` string, nullable, required
          - `resolved_at` string, nullable, required
          - `resolved_by_provider` string, nullable, required
          - `resolved_by_provider_issue_id` string, nullable, required
          - `resolution_reason` string, nullable, required
        - `recurrence_candidates` object[], required
          - `id` string, required
          - `related_task_id` string, required
          - `related_resolved_signal_id` string, nullable, required
          - `confidence` number, required
          - `reason` string, nullable, required
          - `status` string, required
          - `created_at` string, required
          - `reviewed_at` string, nullable, required
          - `related_task` object, nullable
            - `id` string, required
            - `title` string, required
            - `status` string, required

## Other responses

- `400`: Bad request
- `401`: Not authenticated
- `404`: Not found
- `422`: Domain error (non-retryable)
- `500`: Internal server error
- `503`: Domain error (retryable)

---

[API](https://skmtc.dev/usertold/apis/usertold-ai-api.md) · [All operations](https://skmtc.dev/usertold/apis/usertold-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usertold/apis/usertold-ai-api/revisions/37d5b4f88d38?raw)