---
title: "Study Patch"
method: PATCH
path: "/api/orgs/{orgHandle}/projects/{projectHandle}/studies/{studyHandle}"
tags: ["Studies"]
---

# Study Patch

`PATCH /api/orgs/{orgHandle}/projects/{projectHandle}/studies/{studyHandle}`

## 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}/studies/{studyHandle}`
- Auth: none declared

Execute the UserTold study patch operation.

## Path parameters

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

## Request body

- object
  - `title` string
  - `handle` string
  - `description` string, nullable
  - `goals` unknown
  - `script` unknown
  - `settings` unknown
  - `invitation` object, nullable
    - `launcher` object, required
      - `label` string, required
      - `icon` 'feedback' | 'mic' | 'diagram' | 'bug' | 'research', required
      - `style` 'calm' | 'lattice' | 'beam' | 'ticket'
      - `shape` 'capsule' | 'rounded' | 'square'
    - `panel` object
      - `eyebrow` string
      - `headline` string, required
      - `body` string
      - `duration_minutes` integer
      - `reward` object
        - `kind` 'gift' | 'product' | 'community' | 'access', required
        - `label` string, required
        - `eligibility` string
        - `delivery` string
      - `cta` string, required
      - `image` object
        - `asset_id` string, required
        - `url` string, uri, required
        - `alt` string, required
    - `presentation_mode` 'passive' | 'contextual' | 'direct_link', required
    - `brand_color` object, required
      - `light` string, required
      - `dark` string
    - `foreground_color` string
    - `placement` object, required
      - `desktop` 'bottom-left' | 'bottom-right', required
      - `mobile` 'bottom-left' | 'bottom-right', required
  - `visibility` object, nullable
    - `version` 1, required
    - `enabled` boolean, required
    - `rules` object[]
      - `effect` 'include' | 'exclude', required
      - `match` 'exact' | 'subtree', required
      - `pathname` string, required
    - `languages` string[]
    - `priority` integer
    - `order` integer
  - `allowed_selectors` string[]
  - `allowed_origins` string[]
  - `intake_ref` string, nullable
  - `auto_create_intake` boolean
  - `status` string

## Response `200`

Success

- object
  - `study` object, required
    - `ref` string, required
    - `handle` string, required
    - `project_ref` string, required
    - `title` string, required
    - `description` string, nullable, required
    - `status` string, required
    - `goals_json` string, nullable, required
    - `script_json` string, nullable, required
    - `settings_json` string, nullable, required
    - `invitation` object, nullable, required
      - `launcher` object, required
        - `label` string, required
        - `icon` 'feedback' | 'mic' | 'diagram' | 'bug' | 'research', required
        - `style` 'calm' | 'lattice' | 'beam' | 'ticket'
        - `shape` 'capsule' | 'rounded' | 'square'
      - `panel` object
        - `eyebrow` string
        - `headline` string, required
        - `body` string
        - `duration_minutes` integer
        - `reward` object
          - `kind` 'gift' | 'product' | 'community' | 'access', required
          - `label` string, required
          - `eligibility` string
          - `delivery` string
        - `cta` string, required
        - `image` object
          - `asset_id` string, required
          - `url` string, uri, required
          - `alt` string, required
      - `presentation_mode` 'passive' | 'contextual' | 'direct_link', required
      - `brand_color` object, required
        - `light` string, required
        - `dark` string
      - `foreground_color` string
      - `placement` object, required
        - `desktop` 'bottom-left' | 'bottom-right', required
        - `mobile` 'bottom-left' | 'bottom-right', required
    - `invitation_state` 'absent' | 'valid' | 'invalid', required
    - `visibility` object, nullable, required
      - `version` 1, required
      - `enabled` boolean, required
      - `rules` object[]
        - `effect` 'include' | 'exclude', required
        - `match` 'exact' | 'subtree', required
        - `pathname` string, required
      - `languages` string[]
      - `priority` integer
      - `order` integer
    - `visibility_state` 'absent' | 'valid' | 'invalid', required
    - `recruitment_url` string, uri, nullable, required: Shareable customer-page URL for a configured direct-link Invitation; null until an allowed origin is available.
    - `allowed_selectors` string, nullable, required
    - `allowed_origins` string, nullable, required
    - `intake_ref` string, nullable, required
    - `created_at` string, required
    - `updated_at` string, required
  - `intake_status_changed` boolean
  - `warning` string

## Other responses

- `400`: Validation failed: a reserved handle (with code and suggestion) or a plain error for an invalid title, script, handle or origin
- `401`: Not authenticated
- `404`: Not found
- `409`: Study update conflicts with project widget placement or concurrent configuration
- `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)