---
title: "Agent Edit Study"
method: POST
path: "/api/v1/studies/{study_id}/agent"
tags: ["Studies"]
---

# Agent Edit Study

`POST /api/v1/studies/{study_id}/agent`

Execute AI-powered study editing.

Returns the agent's mutations alongside the materialized post-edit state.
By default (`auto_save=True`), changes are persisted to the database with
automatic rollback on failure — same behavior as before this endpoint
started returning mutations. Pass `auto_save=false` to preview the edits
without writing; callers can then POST the mutations to `/agent/apply`
when ready to commit.

`model` selects the agent's underlying LLM:
- "smart" (default): gpt-5.6-sol — highest quality on complex multi-step
  edits, slower and more expensive.
- "fast": gpt-5.6-terra — faster and cheaper. Good for simple
  instructions or preview-and-revise flows.

## Path parameters

- `study_id` string, required

## Request body

- AgentEditRequestV1 — Request for public v1 agent endpoint.
  - `message` string, required
  - `auto_save` boolean
  - `model` 'fast' | 'smart'
  - `language` string, nullable — Optional target language name or code for generated or rewritten participant-facing content.

## Response `200`

Successful Response

- AgentEditResponseV1 — Response from public v1 agent endpoint. Returns the agent's mutations alongside the materialized post-edit state. Customers can either use the materialized fields directly, or POST the mutations to /agent/apply to persist them. Each question in `questions` carries a `mentions` array resolving its `{{Q:...}}` references to `{placeholder, referenced_question_id, label, type, property_name, property_index, valid, error}`, so consumers can render and understand references without parsing tokens. `broken_mentions` lists any invalid references in the post-edit state (entries with `newly_broken=true` were broken by this edit). Randomizer edits are materialized in `routing_nodes`, `routing_branches`, and the routing ownership fields on questions and question groups.
  - `message` string, nullable
  - `mutations` MutationV1[], required
    - `id` string, required
    - `entity_type` 'question' | 'logic_rule' | 'study_settings' | 'study_messages' | 'question_group' | 'routing_composite', required
    - `operation` 'create' | 'update' | 'delete' | 'reorder', required
    - `entity_id` string, nullable
    - `before` object, nullable
    - `after` object, nullable
    - `timestamp` number, required
  - `questions` object[], required
  - `logic` object[], required
  - `study_settings` object, nullable
  - `broken_mentions` BrokenMentionV1[] — Invalid {{Q:...}} references present in the post-edit study state. Empty when all question mentions resolve correctly. Entries with newly_broken=true were broken by this edit.
    - `question_id` string, required
    - `placeholder` string, required
    - `error` string, required
    - `newly_broken` boolean, required
  - `question_groups` object[]
  - `routing_nodes` object[]
  - `routing_branches` object[]

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/getversive/apis/versive-public-api.md) · [All operations](https://skmtc.dev/getversive/apis/versive-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getversive/versive-public-api/revisions/00e66dd838cc/schema)