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

# Agent Apply Mutations

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

Persist a list of agent mutations to the database.

Accepts the `mutations` payload returned by POST /agent, applies them
sequentially with rollback on failure, and returns the resulting study
state.

## Path parameters

- `study_id` string, required

## Request body

- ApplyMutationsRequestV1 — Request for POST /api/v1/studies/{study_id}/agent/apply.
  - `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

## 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)