curl -X POST https://api.getversive.com/api/v1/studies/9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b/agent \ -H "Authorization: Bearer $VERSIVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Add a screener asking how often they cook at home; screen out people who never cook.", "auto_save": false }'
curl -X POST https://api.getversive.com/api/v1/studies/9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b/agent \ -H "Authorization: Bearer $VERSIVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Add a screener asking how often they cook at home; screen out people who never cook.", "auto_save": false }'
Sends a natural-language instruction to Versive’s study-editing agent. The agent can add, edit, delete, and reorder questions, change logic rules, and update study settings and messages. By default changes are saved immediately (with automatic rollback if anything fails); set auto_save: false to preview the mutations and apply them separately.For both default JSON and streaming requests, a detected disconnect cancels
pending work and rolls back an in-progress save. JSON edits no longer continue
in the background after the client or proxy disconnects. Set your client timeout
above the expected edit duration, or use streaming for long edits.
If the save completed before the connection was lost, its acknowledgement may
be missing; inspect the study before retrying.
To copy a fixed list of questions into a study exactly as written, use
Batch create/update questions. It
writes the text and settings you send without a model in between. The agent
writes every question through a model, so a long list takes minutes: use
streaming, and compare the returned questions with your source
before retrying.
string
required
The study ID.
string
default:"application/json"
Set text/event-stream to stream progress and keepalives while the agent runs.
The URL, request body, authentication, and final response fields are unchanged.
string
required
The editing instruction, e.g. “Add an NPS question after the intro and screen out anyone who scores under 3 on Q2.”
boolean
default:"true"
Persist changes before returning. Set false to preview.
string
default:"smart"
smart (higher quality) or fast (lower latency).
string
Language context for the edit.
Response
string | null
The agent’s natural-language summary of what it did.
Mutation[]
The structured change list. Each mutation has id, entity_type (question | logic_rule | study_settings | study_messages), operation (create | update | delete | reorder), entity_id, before, after, and timestamp.
object[]
The study’s questions after the edit, each including a resolved mentions array.
object[]
The study’s logic rules after the edit.
object | null
Updated study settings, when changed.
object[]
Any {{Q:...}} references broken by the edit: question_id, placeholder, error, newly_broken.
curl -X POST https://api.getversive.com/api/v1/studies/9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b/agent \ -H "Authorization: Bearer $VERSIVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Add a screener asking how often they cook at home; screen out people who never cook.", "auto_save": false }'
Streaming
For long edits, send Accept: text/event-stream. The server responds with
Content-Type: text/event-stream, Cache-Control: no-cache, and
X-Accel-Buffering: no. After authorization and setup, it immediately sends
started, then SSE keepalive comments approximately every 15 seconds while
waiting, including during saving.
event: starteddata: {"study_id":"9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b"}: keepaliveevent: progressdata: {"tool":"edit_question","status":"completed","entity_id":"q_8f2"}event: resultdata: {"message":"Updated the question.","mutations":[],"questions":[],"logic":[],"study_settings":null,"broken_mentions":[],"question_groups":[],"question_quotas":[],"routing_nodes":[],"routing_branches":[]}
Event
Data
started
{"study_id":"..."}
progress
{"tool":"...","status":"completed","entity_id":"..."}. The entity ID is omitted when the tool has no single affected entity. Progress is advisory and may be skipped for slow clients.
result
The complete AgentEditResponseV1 JSON, with the same encoding and fields as the default JSON response, including broken_mentions. There is no extra wrapper.
error
{"code":"...","message":"..."}; for example {"code":"agent_execution_failed","message":"Agent execution failed: The request took too long. Please try again."}. Structured save rejections preserve their public code (such as question_limit_exceeded) and message. Client validation failures also include an errors array when rule-level error strings are available, matching the reasons in the JSON response. If no code is provided, HTTP failures use codes such as http_400. Unexpected failures use internal_error.
Each connected stream ends with exactly one terminal event: result or
error, followed by connection close. A client can ignore all other events and
parse the single data: line on result. Tool progress indicates completed
in-memory work; with auto_save: true, mutations are saved beforeresult.
With auto_save: false, result is a preview you can
apply separately.Authentication, access, entitlement, and request/setup validation failures still
return normal HTTP errors before streaming begins. After streaming starts, the
HTTP status is already 200, so clients must handle the terminal error event.When the server detects a disconnect, it cancels pending agent work. A cancelled
save rolls back changes already applied in that batch. If the connection is lost
just after a save completes, the client may miss its result; inspect the study
before retrying. This endpoint does not deduplicate retries or resume streams.
Treat EOF without a terminal event as an interrupted request with an unknown
outcome, and disable automatic retries of this POST.
cURL
Use -N (--no-buffer) to display events as they arrive. Use your regional API
host (api-eu.getversive.com for EU studies).
curl -N --fail-with-body --max-time 900 \ -X POST "https://api-eu.getversive.com/api/v1/studies/$STUDY_ID/agent" \ -H "Authorization: Bearer $VERSIVE_API_KEY" \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -d '{"message":"Add a question about the biggest frustration with onboarding.","auto_save":false}'
Python
This example uses requests. The read timeout limits idle time between received
bytes, rather than the total duration of the edit. The small chunk_size lets
short keepalives and events reach the parser immediately.
import jsonimport osimport requestsurl = f"https://api-eu.getversive.com/api/v1/studies/{os.environ['STUDY_ID']}/agent"with requests.post( url, headers={ "Authorization": f"Bearer {os.environ['VERSIVE_API_KEY']}", "Accept": "text/event-stream", }, json={"message": "Add a question about onboarding frustrations.", "auto_save": False}, stream=True, timeout=(10, 60),) as response: response.raise_for_status() response.encoding = "utf-8" event, data = None, [] for line in response.iter_lines(chunk_size=1, decode_unicode=True): if line.startswith(":"): continue # Keepalive comment if line.startswith("event:"): event = line[6:].strip() elif line.startswith("data:"): data.append(line[5:].lstrip()) elif line == "": if event in ("result", "error"): payload = json.loads("\n".join(data)) if event == "error": raise RuntimeError(f"{payload['code']}: {payload['message']}") print(json.dumps(payload, ensure_ascii=False, indent=2)) break event, data = None, [] else: raise RuntimeError("Stream interrupted; inspect the study before retrying")
Proxy requirements
Every proxy between the client and Versive must forward Accept: text/event-stream
and stream the response immediately, including SSE comments. Disable response
buffering, caching, and compression that buffers small chunks; do not collect the
body with .json() or .text() before forwarding it. For nginx, use
proxy_buffering off and a suitable proxy_read_timeout. Preserve the upstream
content type and cancellation: when the downstream client disconnects, abort the
upstream request too.Set idle timeouts comfortably above 15 seconds (for example, 60 seconds) and allow
a total request duration long enough for the edit. Heartbeats prevent idle read
timeouts only when all intermediaries flush them; they cannot extend an absolute
request-duration limit. Cloudflare documents a default
125-second Proxy Read Timeout.
A buffering customer proxy can still cause a timeout even when Versive streams.To verify the integration, use a test study and check that started appears
promptly, comments arrive during quiet periods, and an edit lasting over 125
seconds still ends in result. On a disposable study, start an edit with
auto_save: true, disconnect while generation is in progress, and confirm the
study remains unchanged after the request has been cancelled. Also remove the
Accept header to confirm the default JSON behavior.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Versive","description":"Documentation for Versive — the AI-powered user research and testing platform","colors":{"primary":"#00786F","light":"#2BB3A8","dark":"#00786F"},"logo":{"light":"https://mintcdn.com/versive/Og7M_uVBtd7MTGJK/logo/light.svg?fit=max\u0026auto=format\u0026n=Og7M_uVBtd7MTGJK\u0026q=85\u0026s=3de4d6717f3a65645f417a61cc68828d","dark":"https://mintcdn.com/versive/Og7M_uVBtd7MTGJK/logo/dark.svg?fit=max\u0026auto=format\u0026n=Og7M_uVBtd7MTGJK\u0026q=85\u0026s=dd51cb606f5301040c8219b572a717fc","href":"https://getversive.com"},"favicon":"https://mintcdn.com/versive/-C2_T5LPeZ5Csg69/favicon.ico?fit=max\u0026auto=format\u0026n=-C2_T5LPeZ5Csg69\u0026q=85\u0026s=ec8e3723f4e24346fcea7c20b5e480ce","api":{"mdx":{"auth":{"method":"bearer"},"server":"https://api.getversive.com/api/v1"}},"navbar":{"links":[{"href":"mailto:[email protected]","label":"Support"}],"primary":{"type":"button","label":"Open Versive","href":"https://getversive.com/login"}},"footer":{"socials":{"website":"https://getversive.com","linkedin":"https://www.linkedin.com/company/versivehq"}},"icons":{"library":"tabler"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"versive","hasAudioNarration":false,"actualSubdomain":"versive","customDomains":["docs.getversive.com"],"gitSource":{"type":"github","owner":"trymirio","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6afb8e0bc23367ba6fcedbdd","clientVersion":"0.0.4167","searchFilterCounts":[{"language":"default","tag":"API reference","count":47},{"language":"default","tag":"Documentation","count":27},{"language":"default","tag":"Studies","count":27},{"language":"default","tag":"AI tests","count":7},{"language":"default","tag":"Interviews","count":5},{"language":"default","tag":"Getting started","count":5},{"language":"default","tag":"Quotas","count":5},{"language":"default","tag":"Question logic","count":4},{"language":"default","tag":"Questions","count":4},{"language":"default","tag":"Randomizers","count":4}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/studies/agent-edit","slug":"/api-reference/studies/agent-edit","pageMetadata":{"title":"Edit study with AI agent","api":"POST /studies/{study_id}/agent","description":"Edit a study with natural-language instructions","href":"/api-reference/studies/agent-edit"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Edit a study with natural-language instructions\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,ParamField,ResponseField,Table,Tip}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Sends a natural-language instruction to Versive’s study-editing agent. The agent can add, edit, delete, and reorder questions, change logic rules, and update study settings and messages. By default changes are `,_jsx(_components.strong,{children:`saved immediately`}),` (with automatic rollback if anything fails); set `,_jsx(_components.code,{children:`auto_save: false`}),` to preview the mutations and `,_jsx(_components.a,{href:`/api-reference/studies/agent-apply`,children:`apply them separately`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`For both default JSON and streaming requests, a detected disconnect cancels\npending work and rolls back an in-progress save. JSON edits no longer continue\nin the background after the client or proxy disconnects. Set your client timeout\nabove the expected edit duration, or use `,_jsx(_components.a,{href:`#streaming`,children:`streaming`}),` for long edits.\nIf the save completed before the connection was lost, its acknowledgement may\nbe missing; inspect the study before retrying.`]}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`To copy a fixed list of questions into a study exactly as written, use\n`,_jsx(_components.a,{href:`/api-reference/questions/batch-questions`,children:`Batch create/update questions`}),`. It\nwrites the text and settings you send without a model in between. The agent\nwrites every question through a model, so a long list takes minutes: use\n`,_jsx(_components.a,{href:`#streaming`,children:`streaming`}),`, and compare the returned `,_jsx(_components.code,{children:`questions`}),` with your source\nbefore retrying.`]})}),`\n`,_jsx(ParamField,{path:`study_id`,type:`string`,required:true,id:`param-study-id`,children:_jsx(_components.p,{children:`The study ID.`})}),`\n`,_jsx(ParamField,{header:`Accept`,type:`string`,default:`application/json`,id:`param-accept`,children:_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`text/event-stream`}),` to stream progress and keepalives while the agent runs.\nThe URL, request body, authentication, and final response fields are unchanged.`]})}),`\n`,_jsx(ParamField,{body:`message`,type:`string`,required:true,id:`param-message`,children:_jsx(_components.p,{children:`The editing instruction, e.g. “Add an NPS question after the intro and screen out anyone who scores under 3 on Q2.”`})}),`\n`,_jsx(ParamField,{body:`auto_save`,type:`boolean`,default:`true`,id:`param-auto-save`,children:_jsxs(_components.p,{children:[`Persist changes before returning. Set `,_jsx(_components.code,{children:`false`}),` to preview.`]})}),`\n`,_jsx(ParamField,{body:`model`,type:`string`,default:`smart`,id:`param-model`,children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`smart`}),` (higher quality) or `,_jsx(_components.code,{children:`fast`}),` (lower latency).`]})}),`\n`,_jsx(ParamField,{body:`language`,type:`string`,id:`param-language`,children:_jsx(_components.p,{children:`Language context for the edit.`})}),`\n`,_jsx(Heading,{level:`3`,id:`response`,children:`Response`}),`\n`,_jsx(ResponseField,{name:`message`,type:`string | null`,id:`param-message-1`,children:_jsx(_components.p,{children:`The agent’s natural-language summary of what it did.`})}),`\n`,_jsx(ResponseField,{name:`mutations`,type:`Mutation[]`,id:`param-mutations`,children:_jsxs(_components.p,{children:[`The structured change list. Each mutation has `,_jsx(_components.code,{children:`id`}),`, `,_jsx(_components.code,{children:`entity_type`}),` (`,_jsx(_components.code,{children:`question`}),` | `,_jsx(_components.code,{children:`logic_rule`}),` | `,_jsx(_components.code,{children:`study_settings`}),` | `,_jsx(_components.code,{children:`study_messages`}),`), `,_jsx(_components.code,{children:`operation`}),` (`,_jsx(_components.code,{children:`create`}),` | `,_jsx(_components.code,{children:`update`}),` | `,_jsx(_components.code,{children:`delete`}),` | `,_jsx(_components.code,{children:`reorder`}),`), `,_jsx(_components.code,{children:`entity_id`}),`, `,_jsx(_components.code,{children:`before`}),`, `,_jsx(_components.code,{children:`after`}),`, and `,_jsx(_components.code,{children:`timestamp`}),`.`]})}),`\n`,_jsx(ResponseField,{name:`questions`,type:`object[]`,id:`param-questions`,children:_jsxs(_components.p,{children:[`The study’s questions after the edit, each including a resolved `,_jsx(_components.code,{children:`mentions`}),` array.`]})}),`\n`,_jsx(ResponseField,{name:`logic`,type:`object[]`,id:`param-logic`,children:_jsx(_components.p,{children:`The study’s logic rules after the edit.`})}),`\n`,_jsx(ResponseField,{name:`study_settings`,type:`object | null`,id:`param-study-settings`,children:_jsx(_components.p,{children:`Updated study settings, when changed.`})}),`\n`,_jsx(ResponseField,{name:`broken_mentions`,type:`object[]`,id:`param-broken-mentions`,children:_jsxs(_components.p,{children:[`Any `,_jsx(_components.code,{children:`{{Q:...}}`}),` references broken by the edit: `,_jsx(_components.code,{children:`question_id`}),`, `,_jsx(_components.code,{children:`placeholder`}),`, `,_jsx(_components.code,{children:`error`}),`, `,_jsx(_components.code,{children:`newly_broken`}),`.`]})}),`\n`,`\n`,_jsx(Heading,{level:`3`,id:`streaming`,children:`Streaming`}),`\n`,_jsxs(_components.p,{children:[`For long edits, send `,_jsx(_components.code,{children:`Accept: text/event-stream`}),`. The server responds with\n`,_jsx(_components.code,{children:`Content-Type: text/event-stream`}),`, `,_jsx(_components.code,{children:`Cache-Control: no-cache`}),`, and\n`,_jsx(_components.code,{children:`X-Accel-Buffering: no`}),`. After authorization and setup, it immediately sends\n`,_jsx(_components.code,{children:`started`}),`, then SSE keepalive comments approximately every 15 seconds while\nwaiting, including during saving.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`12`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`12`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`event: started`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`data: {\"study_id\":\"9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b\"}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`: keepalive`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`event: progress`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`data: {\"tool\":\"edit_question\",\"status\":\"completed\",\"entity_id\":\"q_8f2\"}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`event: result`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`data: {\"message\":\"Updated the question.\",\"mutations\":[],\"questions\":[],\"logic\":[],\"study_settings\":null,\"broken_mentions\":[],\"question_groups\":[],\"question_quotas\":[],\"routing_nodes\":[],\"routing_branches\":[]}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Event`}),_jsx(_components.th,{children:`Data`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`started`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`{\"study_id\":\"...\"}`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`progress`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`{\"tool\":\"...\",\"status\":\"completed\",\"entity_id\":\"...\"}`}),`. The entity ID is omitted when the tool has no single affected entity. Progress is advisory and may be skipped for slow clients.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`result`})}),_jsxs(_components.td,{children:[`The complete `,_jsx(_components.code,{children:`AgentEditResponseV1`}),` JSON, with the same encoding and fields as the default JSON response, including `,_jsx(_components.code,{children:`broken_mentions`}),`. There is no extra wrapper.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`error`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`{\"code\":\"...\",\"message\":\"...\"}`}),`; for example `,_jsx(_components.code,{children:`{\"code\":\"agent_execution_failed\",\"message\":\"Agent execution failed: The request took too long. Please try again.\"}`}),`. Structured save rejections preserve their public `,_jsx(_components.code,{children:`code`}),` (such as `,_jsx(_components.code,{children:`question_limit_exceeded`}),`) and `,_jsx(_components.code,{children:`message`}),`. Client validation failures also include an `,_jsx(_components.code,{children:`errors`}),` array when rule-level error strings are available, matching the reasons in the JSON response. If no code is provided, HTTP failures use codes such as `,_jsx(_components.code,{children:`http_400`}),`. Unexpected failures use `,_jsx(_components.code,{children:`internal_error`}),`.`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[`Each connected stream ends with `,_jsx(_components.strong,{children:`exactly one`}),` terminal event: `,_jsx(_components.code,{children:`result`}),` or\n`,_jsx(_components.code,{children:`error`}),`, followed by connection close. A client can ignore all other events and\nparse the single `,_jsx(_components.code,{children:`data:`}),` line on `,_jsx(_components.code,{children:`result`}),`. Tool progress indicates completed\nin-memory work; with `,_jsx(_components.code,{children:`auto_save: true`}),`, mutations are saved `,_jsx(_components.strong,{children:`before`}),` `,_jsx(_components.code,{children:`result`}),`.\nWith `,_jsx(_components.code,{children:`auto_save: false`}),`, `,_jsx(_components.code,{children:`result`}),` is a preview you can\n`,_jsx(_components.a,{href:`/api-reference/studies/agent-apply`,children:`apply separately`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`Authentication, access, entitlement, and request/setup validation failures still\nreturn normal HTTP errors before streaming begins. After streaming starts, the\nHTTP status is already `,_jsx(_components.code,{children:`200`}),`, so clients must handle the terminal `,_jsx(_components.code,{children:`error`}),` event.`]}),`\n`,_jsxs(_components.p,{children:[`When the server detects a disconnect, it cancels pending agent work. A cancelled\nsave rolls back changes already applied in that batch. If the connection is lost\njust after a save completes, the client may miss its `,_jsx(_components.code,{children:`result`}),`; inspect the study\nbefore retrying. This endpoint does not deduplicate retries or resume streams.\nTreat EOF without a terminal event as an interrupted request with an unknown\noutcome, and disable automatic retries of this POST.`]}),`\n`,_jsx(Heading,{level:`4`,id:`curl`,children:`cURL`}),`\n`,_jsxs(_components.p,{children:[`Use `,_jsx(_components.code,{children:`-N`}),` (`,_jsx(_components.code,{children:`--no-buffer`}),`) to display events as they arrive. Use your regional API\nhost (`,_jsx(_components.code,{children:`api-eu.getversive.com`}),` for EU studies).`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`6`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -N --fail-with-body --max-time 900 \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -X POST `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://api-eu.getversive.com/api/v1/studies/$STUDY_ID/agent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Authorization: Bearer $VERSIVE_API_KEY\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Accept: text/event-stream\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -d `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'{\"message\":\"Add a question about the biggest frustration with onboarding.\",\"auto_save\":false}'`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`4`,id:`python`,children:`Python`}),`\n`,_jsxs(_components.p,{children:[`This example uses `,_jsx(_components.code,{children:`requests`}),`. The read timeout limits idle time between received\nbytes, rather than the total duration of the edit. The small `,_jsx(_components.code,{children:`chunk_size`}),` lets\nshort keepalives and events reach the parser immediately.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`36`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`36`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` json`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` os`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requests`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`url = f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://api-eu.getversive.com/api/v1/studies/{os.environ['STUDY_ID']}/agent\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`with`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requests.post(`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` url,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` headers={`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bearer {os.environ['VERSIVE_API_KEY']}\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Accept\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"text/event-stream\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` json={`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Add a question about onboarding frustrations.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"auto_save\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`False`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` stream=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` timeout=(10, 60),`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`as`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.raise_for_status()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.encoding = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"utf-8\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event, data = `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`None`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, []`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.iter_lines(chunk_size=1, decode_unicode=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line.startswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\":\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` continue`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Keepalive comment`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line.startswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"event:\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event = line[6:].strip()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` elif`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line.startswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"data:\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` data.append(line[5:].lstrip())`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` elif`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line == `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"result\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` payload = json.loads(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\\\\n\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.join(data))`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event == `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` raise`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` RuntimeError(f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"{payload['code']}: {payload['message']}\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` print(json.dumps(payload, ensure_ascii=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`False`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, indent=2))`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` break`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event, data = `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`None`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, []`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` else`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` raise`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` RuntimeError(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Stream interrupted; inspect the study before retrying\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`4`,id:`proxy-requirements`,children:`Proxy requirements`}),`\n`,_jsxs(_components.p,{children:[`Every proxy between the client and Versive must forward `,_jsx(_components.code,{children:`Accept: text/event-stream`}),`\nand stream the response immediately, including SSE comments. Disable response\nbuffering, caching, and compression that buffers small chunks; do not collect the\nbody with `,_jsx(_components.code,{children:`.json()`}),` or `,_jsx(_components.code,{children:`.text()`}),` before forwarding it. For nginx, use\n`,_jsx(_components.code,{children:`proxy_buffering off`}),` and a suitable `,_jsx(_components.code,{children:`proxy_read_timeout`}),`. Preserve the upstream\ncontent type and cancellation: when the downstream client disconnects, abort the\nupstream request too.`]}),`\n`,_jsxs(_components.p,{children:[`Set idle timeouts comfortably above 15 seconds (for example, 60 seconds) and allow\na total request duration long enough for the edit. Heartbeats prevent idle read\ntimeouts only when all intermediaries flush them; they cannot extend an absolute\nrequest-duration limit. Cloudflare documents a default\n`,_jsx(_components.a,{href:`https://developers.cloudflare.com/fundamentals/reference/connection-limits/`,children:`125-second Proxy Read Timeout`}),`.\nA buffering customer proxy can still cause a timeout even when Versive streams.`]}),`\n`,_jsxs(_components.p,{children:[`To verify the integration, use a test study and check that `,_jsx(_components.code,{children:`started`}),` appears\npromptly, comments arrive during quiet periods, and an edit lasting over 125\nseconds still ends in `,_jsx(_components.code,{children:`result`}),`. On a disposable study, start an edit with\n`,_jsx(_components.code,{children:`auto_save: true`}),`, disconnect while generation is in progress, and confirm the\nstudy remains unchanged after the request has been cancelled. Also remove the\n`,_jsx(_components.code,{children:`Accept`}),` header to confirm the default JSON behavior.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Edit study with AI agent","api":"POST /studies/{study_id}/agent","description":"Edit a study with natural-language instructions","href":"/api-reference/studies/agent-edit"}}},"mdxSourceWithNoJs":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,ParamField,RequestExample,ResponseField,Table,Tip}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!ParamField)_missingMdxReference(`ParamField`,true);if(!RequestExample)_missingMdxReference(`RequestExample`,true);if(!ResponseField)_missingMdxReference(`ResponseField`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Tip)_missingMdxReference(`Tip`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Sends a natural-language instruction to Versive’s study-editing agent. The agent can add, edit, delete, and reorder questions, change logic rules, and update study settings and messages. By default changes are `,_jsx(_components.strong,{children:`saved immediately`}),` (with automatic rollback if anything fails); set `,_jsx(_components.code,{children:`auto_save: false`}),` to preview the mutations and `,_jsx(_components.a,{href:`/api-reference/studies/agent-apply`,children:`apply them separately`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`For both default JSON and streaming requests, a detected disconnect cancels\npending work and rolls back an in-progress save. JSON edits no longer continue\nin the background after the client or proxy disconnects. Set your client timeout\nabove the expected edit duration, or use `,_jsx(_components.a,{href:`#streaming`,children:`streaming`}),` for long edits.\nIf the save completed before the connection was lost, its acknowledgement may\nbe missing; inspect the study before retrying.`]}),`\n`,_jsx(Tip,{children:_jsxs(_components.p,{children:[`To copy a fixed list of questions into a study exactly as written, use\n`,_jsx(_components.a,{href:`/api-reference/questions/batch-questions`,children:`Batch create/update questions`}),`. It\nwrites the text and settings you send without a model in between. The agent\nwrites every question through a model, so a long list takes minutes: use\n`,_jsx(_components.a,{href:`#streaming`,children:`streaming`}),`, and compare the returned `,_jsx(_components.code,{children:`questions`}),` with your source\nbefore retrying.`]})}),`\n`,_jsx(ParamField,{path:`study_id`,type:`string`,required:true,id:`param-study-id`,children:_jsx(_components.p,{children:`The study ID.`})}),`\n`,_jsx(ParamField,{header:`Accept`,type:`string`,default:`application/json`,id:`param-accept`,children:_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`text/event-stream`}),` to stream progress and keepalives while the agent runs.\nThe URL, request body, authentication, and final response fields are unchanged.`]})}),`\n`,_jsx(ParamField,{body:`message`,type:`string`,required:true,id:`param-message`,children:_jsx(_components.p,{children:`The editing instruction, e.g. “Add an NPS question after the intro and screen out anyone who scores under 3 on Q2.”`})}),`\n`,_jsx(ParamField,{body:`auto_save`,type:`boolean`,default:`true`,id:`param-auto-save`,children:_jsxs(_components.p,{children:[`Persist changes before returning. Set `,_jsx(_components.code,{children:`false`}),` to preview.`]})}),`\n`,_jsx(ParamField,{body:`model`,type:`string`,default:`smart`,id:`param-model`,children:_jsxs(_components.p,{children:[_jsx(_components.code,{children:`smart`}),` (higher quality) or `,_jsx(_components.code,{children:`fast`}),` (lower latency).`]})}),`\n`,_jsx(ParamField,{body:`language`,type:`string`,id:`param-language`,children:_jsx(_components.p,{children:`Language context for the edit.`})}),`\n`,_jsx(Heading,{level:`3`,id:`response`,children:`Response`}),`\n`,_jsx(ResponseField,{name:`message`,type:`string | null`,id:`param-message-1`,children:_jsx(_components.p,{children:`The agent’s natural-language summary of what it did.`})}),`\n`,_jsx(ResponseField,{name:`mutations`,type:`Mutation[]`,id:`param-mutations`,children:_jsxs(_components.p,{children:[`The structured change list. Each mutation has `,_jsx(_components.code,{children:`id`}),`, `,_jsx(_components.code,{children:`entity_type`}),` (`,_jsx(_components.code,{children:`question`}),` | `,_jsx(_components.code,{children:`logic_rule`}),` | `,_jsx(_components.code,{children:`study_settings`}),` | `,_jsx(_components.code,{children:`study_messages`}),`), `,_jsx(_components.code,{children:`operation`}),` (`,_jsx(_components.code,{children:`create`}),` | `,_jsx(_components.code,{children:`update`}),` | `,_jsx(_components.code,{children:`delete`}),` | `,_jsx(_components.code,{children:`reorder`}),`), `,_jsx(_components.code,{children:`entity_id`}),`, `,_jsx(_components.code,{children:`before`}),`, `,_jsx(_components.code,{children:`after`}),`, and `,_jsx(_components.code,{children:`timestamp`}),`.`]})}),`\n`,_jsx(ResponseField,{name:`questions`,type:`object[]`,id:`param-questions`,children:_jsxs(_components.p,{children:[`The study’s questions after the edit, each including a resolved `,_jsx(_components.code,{children:`mentions`}),` array.`]})}),`\n`,_jsx(ResponseField,{name:`logic`,type:`object[]`,id:`param-logic`,children:_jsx(_components.p,{children:`The study’s logic rules after the edit.`})}),`\n`,_jsx(ResponseField,{name:`study_settings`,type:`object | null`,id:`param-study-settings`,children:_jsx(_components.p,{children:`Updated study settings, when changed.`})}),`\n`,_jsx(ResponseField,{name:`broken_mentions`,type:`object[]`,id:`param-broken-mentions`,children:_jsxs(_components.p,{children:[`Any `,_jsx(_components.code,{children:`{{Q:...}}`}),` references broken by the edit: `,_jsx(_components.code,{children:`question_id`}),`, `,_jsx(_components.code,{children:`placeholder`}),`, `,_jsx(_components.code,{children:`error`}),`, `,_jsx(_components.code,{children:`newly_broken`}),`.`]})}),`\n`,_jsx(RequestExample,{children:_jsx(CodeBlock,{filename:`cURL`,numberOfLines:`7`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`7`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -X POST https://api.getversive.com/api/v1/studies/9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b/agent \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Authorization: Bearer $VERSIVE_API_KEY\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -d `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'{`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"message\": \"Add a screener asking how often they cook at home; screen out people who never cook.\",`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"auto_save\": false`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` }'`})}),`\n`]})})})}),`\n`,_jsx(Heading,{level:`3`,id:`streaming`,children:`Streaming`}),`\n`,_jsxs(_components.p,{children:[`For long edits, send `,_jsx(_components.code,{children:`Accept: text/event-stream`}),`. The server responds with\n`,_jsx(_components.code,{children:`Content-Type: text/event-stream`}),`, `,_jsx(_components.code,{children:`Cache-Control: no-cache`}),`, and\n`,_jsx(_components.code,{children:`X-Accel-Buffering: no`}),`. After authorization and setup, it immediately sends\n`,_jsx(_components.code,{children:`started`}),`, then SSE keepalive comments approximately every 15 seconds while\nwaiting, including during saving.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`12`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`12`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`event: started`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`data: {\"study_id\":\"9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b\"}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`: keepalive`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`event: progress`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`data: {\"tool\":\"edit_question\",\"status\":\"completed\",\"entity_id\":\"q_8f2\"}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`event: result`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`data: {\"message\":\"Updated the question.\",\"mutations\":[],\"questions\":[],\"logic\":[],\"study_settings\":null,\"broken_mentions\":[],\"question_groups\":[],\"question_quotas\":[],\"routing_nodes\":[],\"routing_branches\":[]}`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Event`}),_jsx(_components.th,{children:`Data`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`started`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`{\"study_id\":\"...\"}`})})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`progress`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`{\"tool\":\"...\",\"status\":\"completed\",\"entity_id\":\"...\"}`}),`. The entity ID is omitted when the tool has no single affected entity. Progress is advisory and may be skipped for slow clients.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`result`})}),_jsxs(_components.td,{children:[`The complete `,_jsx(_components.code,{children:`AgentEditResponseV1`}),` JSON, with the same encoding and fields as the default JSON response, including `,_jsx(_components.code,{children:`broken_mentions`}),`. There is no extra wrapper.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`error`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`{\"code\":\"...\",\"message\":\"...\"}`}),`; for example `,_jsx(_components.code,{children:`{\"code\":\"agent_execution_failed\",\"message\":\"Agent execution failed: The request took too long. Please try again.\"}`}),`. Structured save rejections preserve their public `,_jsx(_components.code,{children:`code`}),` (such as `,_jsx(_components.code,{children:`question_limit_exceeded`}),`) and `,_jsx(_components.code,{children:`message`}),`. Client validation failures also include an `,_jsx(_components.code,{children:`errors`}),` array when rule-level error strings are available, matching the reasons in the JSON response. If no code is provided, HTTP failures use codes such as `,_jsx(_components.code,{children:`http_400`}),`. Unexpected failures use `,_jsx(_components.code,{children:`internal_error`}),`.`]})]})]})]}),`\n`,_jsxs(_components.p,{children:[`Each connected stream ends with `,_jsx(_components.strong,{children:`exactly one`}),` terminal event: `,_jsx(_components.code,{children:`result`}),` or\n`,_jsx(_components.code,{children:`error`}),`, followed by connection close. A client can ignore all other events and\nparse the single `,_jsx(_components.code,{children:`data:`}),` line on `,_jsx(_components.code,{children:`result`}),`. Tool progress indicates completed\nin-memory work; with `,_jsx(_components.code,{children:`auto_save: true`}),`, mutations are saved `,_jsx(_components.strong,{children:`before`}),` `,_jsx(_components.code,{children:`result`}),`.\nWith `,_jsx(_components.code,{children:`auto_save: false`}),`, `,_jsx(_components.code,{children:`result`}),` is a preview you can\n`,_jsx(_components.a,{href:`/api-reference/studies/agent-apply`,children:`apply separately`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`Authentication, access, entitlement, and request/setup validation failures still\nreturn normal HTTP errors before streaming begins. After streaming starts, the\nHTTP status is already `,_jsx(_components.code,{children:`200`}),`, so clients must handle the terminal `,_jsx(_components.code,{children:`error`}),` event.`]}),`\n`,_jsxs(_components.p,{children:[`When the server detects a disconnect, it cancels pending agent work. A cancelled\nsave rolls back changes already applied in that batch. If the connection is lost\njust after a save completes, the client may miss its `,_jsx(_components.code,{children:`result`}),`; inspect the study\nbefore retrying. This endpoint does not deduplicate retries or resume streams.\nTreat EOF without a terminal event as an interrupted request with an unknown\noutcome, and disable automatic retries of this POST.`]}),`\n`,_jsx(Heading,{level:`4`,id:`curl`,children:`cURL`}),`\n`,_jsxs(_components.p,{children:[`Use `,_jsx(_components.code,{children:`-N`}),` (`,_jsx(_components.code,{children:`--no-buffer`}),`) to display events as they arrive. Use your regional API\nhost (`,_jsx(_components.code,{children:`api-eu.getversive.com`}),` for EU studies).`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`6`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`6`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#8250DF`,\"--shiki-dark\":`#DCDCAA`},children:`curl`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -N --fail-with-body --max-time 900 \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -X POST `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://api-eu.getversive.com/api/v1/studies/$STUDY_ID/agent\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Authorization: Bearer $VERSIVE_API_KEY\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Content-Type: application/json\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -H `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Accept: text/event-stream\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` \\\\`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` -d `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`'{\"message\":\"Add a question about the biggest frustration with onboarding.\",\"auto_save\":false}'`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`4`,id:`python`,children:`Python`}),`\n`,_jsxs(_components.p,{children:[`This example uses `,_jsx(_components.code,{children:`requests`}),`. The read timeout limits idle time between received\nbytes, rather than the total duration of the edit. The small `,_jsx(_components.code,{children:`chunk_size`}),` lets\nshort keepalives and events reach the parser immediately.`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`36`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`36`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` json`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` os`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`import`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requests`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`url = f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"https://api-eu.getversive.com/api/v1/studies/{os.environ['STUDY_ID']}/agent\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`with`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` requests.post(`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` url,`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` headers={`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Authorization\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Bearer {os.environ['VERSIVE_API_KEY']}\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` \"Accept\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"text/event-stream\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` },`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` json={`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"message\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Add a question about onboarding frustrations.\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"auto_save\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`: `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`False`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`},`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` stream=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`,`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` timeout=(10, 60),`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`) `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`as`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response:`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.raise_for_status()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.encoding = `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"utf-8\"`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event, data = `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`None`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, []`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` for`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` response.iter_lines(chunk_size=1, decode_unicode=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`True`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line.startswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\":\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` continue`}),_jsx(_components.span,{style:{color:`#6E7781`,\"--shiki-dark\":`#6A9955`},children:` # Keepalive comment`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line.startswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"event:\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event = line[6:].strip()`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` elif`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line.startswith(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"data:\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` data.append(line[5:].lstrip())`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` elif`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` line == `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`in`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` (`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"result\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`):`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` payload = json.loads(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"\\\\n\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`.join(data))`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` if`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event == `}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"error\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` raise`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` RuntimeError(f`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"{payload['code']}: {payload['message']}\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` print(json.dumps(payload, ensure_ascii=`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`False`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, indent=2))`})]}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` break`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` event, data = `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:`None`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`, []`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` else`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#C586C0`},children:` raise`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` RuntimeError(`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`\"Stream interrupted; inspect the study before retrying\"`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`)`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`4`,id:`proxy-requirements`,children:`Proxy requirements`}),`\n`,_jsxs(_components.p,{children:[`Every proxy between the client and Versive must forward `,_jsx(_components.code,{children:`Accept: text/event-stream`}),`\nand stream the response immediately, including SSE comments. Disable response\nbuffering, caching, and compression that buffers small chunks; do not collect the\nbody with `,_jsx(_components.code,{children:`.json()`}),` or `,_jsx(_components.code,{children:`.text()`}),` before forwarding it. For nginx, use\n`,_jsx(_components.code,{children:`proxy_buffering off`}),` and a suitable `,_jsx(_components.code,{children:`proxy_read_timeout`}),`. Preserve the upstream\ncontent type and cancellation: when the downstream client disconnects, abort the\nupstream request too.`]}),`\n`,_jsxs(_components.p,{children:[`Set idle timeouts comfortably above 15 seconds (for example, 60 seconds) and allow\na total request duration long enough for the edit. Heartbeats prevent idle read\ntimeouts only when all intermediaries flush them; they cannot extend an absolute\nrequest-duration limit. Cloudflare documents a default\n`,_jsx(_components.a,{href:`https://developers.cloudflare.com/fundamentals/reference/connection-limits/`,children:`125-second Proxy Read Timeout`}),`.\nA buffering customer proxy can still cause a timeout even when Versive streams.`]}),`\n`,_jsxs(_components.p,{children:[`To verify the integration, use a test study and check that `,_jsx(_components.code,{children:`started`}),` appears\npromptly, comments arrive during quiet periods, and an edit lasting over 125\nseconds still ends in `,_jsx(_components.code,{children:`result`}),`. On a disposable study, start an edit with\n`,_jsx(_components.code,{children:`auto_save: true`}),`, disconnect while generation is in progress, and confirm the\nstudy remains unchanged after the request has been cancelled. Also remove the\n`,_jsx(_components.code,{children:`Accept`}),` header to confirm the default JSON behavior.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Edit study with AI agent","api":"POST /studies/{study_id}/agent","description":"Edit a study with natural-language instructions","href":"/api-reference/studies/agent-edit"}}}},"mdxExtracts":{"tableOfContents":[{"title":"Response","slug":"response","depth":3,"children":[]},{"title":"Streaming","slug":"streaming","depth":3,"children":[]},{"title":"cURL","slug":"curl","depth":4,"children":[]},{"title":"Python","slug":"python","depth":4,"children":[]},{"title":"Proxy requirements","slug":"proxy-requirements","depth":4,"children":[]}],"codeExamples":{"request":{"type":"RequestExample","children":[{"filename":"cURL","html":"\u003cpre class=\"shiki shiki-themes github-light-default dark-plus\" style=\"background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4\" language=\"shellscript\">\u003ccode language=\"shellscript\" numberOfLines=\"7\">\u003cspan class=\"line\">\u003cspan style=\"color:#8250DF;--shiki-dark:#DCDCAA\">curl\u003c/span>\u003cspan style=\"color:#1F2328;--shiki-dark:#D4D4D4\"> -X POST https://api.getversive.com/api/v1/studies/9b2f7c1e-4a4b-4f6e-9a1d-1c2d3e4f5a6b/agent \\\u003c/span>\u003c/span>\n\u003cspan class=\"line\">\u003cspan style=\"color:#1F2328;--shiki-dark:#D4D4D4\"> -H \u003c/span>\u003cspan style=\"color:#0A3069;--shiki-dark:#CE9178\">\"Authorization: Bearer $VERSIVE_API_KEY\"\u003c/span>\u003cspan style=\"color:#1F2328;--shiki-dark:#D4D4D4\"> \\\u003c/span>\u003c/span>\n\u003cspan class=\"line\">\u003cspan style=\"color:#1F2328;--shiki-dark:#D4D4D4\"> -H \u003c/span>\u003cspan style=\"color:#0A3069;--shiki-dark:#CE9178\">\"Content-Type: application/json\"\u003c/span>\u003cspan style=\"color:#1F2328;--shiki-dark:#D4D4D4\"> \\\u003c/span>\u003c/span>\n\u003cspan class=\"line\">\u003cspan style=\"color:#1F2328;--shiki-dark:#D4D4D4\"> -d \u003c/span>\u003cspan style=\"color:#0A3069;--shiki-dark:#CE9178\">'{\u003c/span>\u003c/span>\n\u003cspan class=\"line\">\u003cspan style=\"color:#0A3069;--shiki-dark:#CE9178\"> \"message\": \"Add a screener asking how often they cook at home; screen out people who never cook.\",\u003c/span>\u003c/span>\n\u003cspan class=\"line\">\u003cspan style=\"color:#0A3069;--shiki-dark:#CE9178\"> \"auto_save\": false\u003c/span>\u003c/span>\n\u003cspan class=\"line\">\u003cspan style=\"color:#0A3069;--shiki-dark:#CE9178\"> }'\u003c/span>\u003c/span>\n\u003c/code>\u003c/pre>"}],"attributes":[]}},"endpoint":{"title":"Edit study with AI agent","path":"/studies/{study_id}/agent","servers":[{"url":"https://api.getversive.com/api/v1"}],"method":"post","request":{"security":[{"title":"Bearer Auth","parameters":{"header":{"Authorization":{"type":"http","scheme":"bearer","description":"Bearer authentication header of the form `Bearer \u003ctoken>`, where `\u003ctoken>` is your auth token."}},"query":{},"cookie":{}}}],"parameters":{"query":{},"header":{"Accept":{"schema":[{"type":"string","description":"Set `text/event-stream` to stream progress and keepalives while the agent runs. The URL, request body, authentication, and final response fields are unchanged."}]}},"cookie":{},"path":{"study_id":{"schema":[{"type":"string","description":"The study ID.","required":true}]}}},"body":{"application/json":{"schemaArray":[{"type":"object","properties":{"message":[{"type":"string","description":"The editing instruction, e.g. “Add an NPS question after the intro and screen out anyone who scores under 3 on Q2.”","required":true}],"auto_save":[{"type":"boolean","description":"Persist changes before returning. Set `false` to preview."}],"model":[{"type":"string","description":"`smart` (higher quality) or `fast` (lower latency)."}],"language":[{"type":"string","description":"Language context for the edit."}]}}],"examples":{"example":{"value":{"message":"\u003cstring>","auto_save":true,"model":"\u003cstring>","language":"\u003cstring>"}}}}}},"response":{"200":{"application/json":{"schemaArray":[{"type":"object","properties":{"message":[{"type":"object","properties":{},"description":"The agent’s natural-language summary of what it did."}],"mutations":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"The structured change list. Each mutation has `id` , `entity_type` ( `question` | `logic_rule` | `study_settings` | `study_messages` ), `operation` ( `create` | `update` | `delete` | `reorder` ), `entity_id` , `before` , `after` , and `timestamp` ."}],"questions":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"The study’s questions after the edit, each including a resolved `mentions` array."}],"logic":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"The study’s logic rules after the edit."}],"study_settings":[{"type":"object","properties":{},"description":"Updated study settings, when changed."}],"broken_mentions":[{"type":"array","items":[{"type":"object","properties":{}}],"description":"Any `{{Q:...}}` references broken by the edit: `question_id` , `placeholder` , `error` , `newly_broken` ."}]}}],"examples":{"example":{"value":{"message":{},"mutations":[{}],"questions":[{}],"logic":[{}],"study_settings":{},"broken_mentions":[{}]}}}}}},"deprecated":false}},"jsLinks":[],"subdomain":"versive","siteName":"Versive","title":"Edit study with AI agent - Versive","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-27T21:15:18.804Z","originalFileLocation":"api-reference/studies/agent-edit.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Edit a study with natural-language instructions\">\u003cmeta data-mint-head name=\"application-name\" content=\"Versive\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/x-icon\" sizes=\"180x180\" href=\"https://mintcdn.com/versive/-C2_T5LPeZ5Csg69/favicon.ico?fit=max\u0026amp;auto=format\u0026amp;n=-C2_T5LPeZ5Csg69\u0026amp;q=85\u0026amp;s=ec8e3723f4e24346fcea7c20b5e480ce\">\u003clink data-mint-head rel=\"icon\" type=\"image/x-icon\" sizes=\"32x32\" href=\"https://mintcdn.com/versive/-C2_T5LPeZ5Csg69/favicon.ico?fit=max\u0026amp;auto=format\u0026amp;n=-C2_T5LPeZ5Csg69\u0026amp;q=85\u0026amp;s=ec8e3723f4e24346fcea7c20b5e480ce\">\u003clink data-mint-head rel=\"icon\" type=\"image/x-icon\" sizes=\"16x16\" href=\"https://mintcdn.com/versive/-C2_T5LPeZ5Csg69/favicon.ico?fit=max\u0026amp;auto=format\u0026amp;n=-C2_T5LPeZ5Csg69\u0026amp;q=85\u0026amp;s=ec8e3723f4e24346fcea7c20b5e480ce\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"https://mintcdn.com/versive/-C2_T5LPeZ5Csg69/favicon.ico?fit=max\u0026amp;auto=format\u0026amp;n=-C2_T5LPeZ5Csg69\u0026amp;q=85\u0026amp;s=ec8e3723f4e24346fcea7c20b5e480ce\">\u003cmeta data-mint-head property=\"og:title\" content=\"Edit study with AI agent - Versive\">\u003cmeta data-mint-head property=\"og:description\" content=\"Edit a study with natural-language instructions\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Versive\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.getversive.com/api-reference/studies/agent-edit\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://versive.mintlify.site/_mintlify/api/og/v2?division=Studies\u0026amp;title=Edit+study+with+AI+agent\u0026amp;description=Edit+a+study+with+natural-language+instructions\u0026amp;theme=320d8c7891ebe44ce8a03901\u0026amp;signature=e0f948abbd27ff050b98a4f9ec1ccd14c9c43155333ecd7187723eb3df8222bd\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Edit study with AI agent - Versive\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Edit a study with natural-language instructions\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://versive.mintlify.site/_mintlify/api/og/v2?division=Studies\u0026amp;title=Edit+study+with+AI+agent\u0026amp;description=Edit+a+study+with+natural-language+instructions\u0026amp;theme=320d8c7891ebe44ce8a03901\u0026amp;signature=e0f948abbd27ff050b98a4f9ec1ccd14c9c43155333ecd7187723eb3df8222bd\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"https://mintlify.s3.us-west-1.amazonaws.com/versive/_generated/favicon/browserconfig.xml?v=3\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Versive\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#00786F\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.getversive.com/api-reference/studies/agent-edit\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/studies/agent-edit.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.getversive.com/#organization\",\"name\":\"Versive\",\"url\":\"https://docs.getversive.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/versive/Og7M_uVBtd7MTGJK/logo/light.svg?fit=max\u0026auto=format\u0026n=Og7M_uVBtd7MTGJK\u0026q=85\u0026s=3de4d6717f3a65645f417a61cc68828d\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.getversive.com#website\",\"name\":\"Versive\",\"url\":\"https://docs.getversive.com\",\"publisher\":{\"@id\":\"https://docs.getversive.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.getversive.com/api-reference/studies/agent-edit#webpage\",\"url\":\"https://docs.getversive.com/api-reference/studies/agent-edit\",\"name\":\"Edit study with AI agent\",\"description\":\"Edit a study with natural-language instructions\",\"dateModified\":\"2026-10-27T21:15:18.804Z\",\"isPartOf\":{\"@id\":\"https://docs.getversive.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.getversive.com/api-reference/studies/agent-edit#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.getversive.com/api-reference/studies/agent-edit#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Studies\",\"item\":\"https://docs.getversive.com/api-reference/studies/create-study\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Edit study with AI agent\",\"item\":\"https://docs.getversive.com/api-reference/studies/agent-edit\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.getversive.com/api-reference/studies/agent-edit#apireference\",\"headline\":\"Edit study with AI agent\",\"name\":\"Edit study with AI agent\",\"description\":\"Edit a study with natural-language instructions\",\"url\":\"https://docs.getversive.com/api-reference/studies/agent-edit\",\"mainEntityOfPage\":{\"@id\":\"https://docs.getversive.com/api-reference/studies/agent-edit#webpage\"},\"dateModified\":\"2026-10-27T21:15:18.804Z\",\"publisher\":{\"@id\":\"https://docs.getversive.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.getversive.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Versive\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Versive\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/studies/agent-edit.md","siteName":"Versive","nav":{"global":null,"tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":""}]},{"tab":"API reference","groups":[{"group":"Getting started","pages":[{"title":"API introduction","sidebarTitle":"Introduction","href":"/api-reference/introduction"},{"title":"Versioning and compatibility","sidebarTitle":"Versioning","href":"/api-reference/versioning"},{"title":"Webhooks","sidebarTitle":"Webhooks","href":"/api-reference/webhooks"}]},{"group":"Studies","pages":[{"title":"Create study","api":"POST /studies","href":"/api-reference/studies/create-study"},{"title":"List studies","api":"GET /studies","href":"/api-reference/studies/list-studies"},{"title":"Get study","api":"GET /studies/{id}","href":"/api-reference/studies/get-study"},{"title":"Update study","api":"PUT /studies/{id}","href":"/api-reference/studies/update-study"},{"title":"Get study metrics","api":"GET /studies/{id}/metrics","href":"/api-reference/studies/get-study-metrics"},{"title":"Review study","api":"GET /studies/{id}/review","href":"/api-reference/studies/review-study"},{"title":"Estimate study length","api":"POST /studies/length-estimate","href":"/api-reference/studies/estimate-study-length"},{"title":"Translate study","api":"POST /studies/{id}/translate","href":"/api-reference/studies/translate-study"},{"title":"List study translations","api":"GET /studies/{id}/translations","description":"Read all translated questions for a study","href":"/api-reference/studies/list-study-translations"},{"title":"Edit study with AI agent","api":"POST /studies/{study_id}/agent","href":"/api-reference/studies/agent-edit"},{"title":"Apply agent mutations","api":"POST /studies/{study_id}/agent/apply","description":"Persist mutations from a previewed agent edit","href":"/api-reference/studies/agent-apply"},{"title":"AI edit questions (stateless)","api":"POST /studies/{study_id}/ai-edit","href":"/api-reference/studies/ai-edit"},{"title":"List available references","api":"GET /studies/{study_id}/available-references","href":"/api-reference/studies/available-references"}]},{"group":"Quotas","pages":[{"title":"Get study quotas","api":"GET /studies/{id}/quotas","href":"/api-reference/quotas/get-study-quotas"},{"title":"Update study quotas","api":"PUT /studies/{id}/quotas","href":"/api-reference/quotas/update-study-quotas"},{"title":"Get quota progress","api":"GET /studies/{id}/quotas/progress","href":"/api-reference/quotas/get-quota-progress"},{"title":"List question quotas","api":"GET /studies/{id}/question-quotas","href":"/api-reference/quotas/list-question-quotas"},{"title":"Update question quotas","api":"PUT /studies/{id}/questions/{question_id}/quotas","href":"/api-reference/quotas/update-question-quotas"}]},{"group":"Randomizers","pages":[{"title":"List randomizers","api":"GET /randomizers","href":"/api-reference/randomizers/list-randomizers"},{"title":"Create randomizer","api":"POST /randomizers","href":"/api-reference/randomizers/create-randomizer"},{"title":"Update randomizer","api":"PUT /randomizers/{id}","href":"/api-reference/randomizers/update-randomizer"},{"title":"Remove randomizer","api":"POST /randomizers/{id}/remove","href":"/api-reference/randomizers/remove-randomizer"}]},{"group":"Questions","pages":[{"title":"List questions","api":"GET /questions","href":"/api-reference/questions/list-questions"},{"title":"Batch create/update questions","api":"POST /questions/batch","href":"/api-reference/questions/batch-questions"},{"title":"Update question","api":"PUT /questions/{question_id}","href":"/api-reference/questions/update-question"},{"title":"Delete question","api":"DELETE /questions/{question_id}","href":"/api-reference/questions/delete-question"}]},{"group":"Asset uploads","pages":[{"title":"Create asset upload","api":"POST /asset-uploads","href":"/api-reference/asset-uploads/create-asset-upload"},{"title":"Complete asset upload","api":"POST /asset-uploads/{upload_id}/complete","href":"/api-reference/asset-uploads/complete-asset-upload"}]},{"group":"Question logic","pages":[{"title":"List question logic","api":"GET /question-logic","href":"/api-reference/question-logic/list-question-logic"},{"title":"Create question logic","api":"POST /question-logic","href":"/api-reference/question-logic/create-question-logic"},{"title":"Update question logic","api":"PUT /question-logic/{logic_id}","href":"/api-reference/question-logic/update-question-logic"},{"title":"Delete question logic","api":"DELETE /question-logic/{logic_id}","href":"/api-reference/question-logic/delete-question-logic"}]},{"group":"Interviews","pages":[{"title":"Create interview","api":"POST /interviews","href":"/api-reference/interviews/create-interview"},{"title":"Get interview","api":"GET /interviews/{id}","href":"/api-reference/interviews/get-interview"},{"title":"Get interview by link token","api":"GET /interviews","href":"/api-reference/interviews/get-interview-by-vid"},{"title":"Get interview media","api":"GET /interviews/{id}/media","href":"/api-reference/interviews/get-interview-media"},{"title":"Update interview","api":"PUT /interviews/{id}","href":"/api-reference/interviews/update-interview"}]},{"group":"Insights","pages":[{"title":"Get interview insights","api":"GET /insights","href":"/api-reference/insights/get-insights"}]},{"group":"Translated questions","pages":[{"title":"List translated questions","api":"GET /translated-questions","href":"/api-reference/translated-questions/list-translated-questions"},{"title":"Get translated question","api":"GET /translated-questions/{translated_question_id}","href":"/api-reference/translated-questions/get-translated-question"},{"title":"Update translated question","api":"PUT /translated-questions/{translated_question_id}","href":"/api-reference/translated-questions/update-translated-question"}]},{"group":"Folders","pages":[{"title":"Create folder","api":"POST /folders","href":"/api-reference/folders/create-folder"},{"title":"List folders","api":"GET /folders","href":"/api-reference/folders/list-folders"},{"title":"Update folder","api":"PATCH /folders/{id}","href":"/api-reference/folders/update-folder"}]}]},{"tab":"MCP","pages":[{"title":"MCP","href":"/mcp/overview"}]},{"tab":"SDK","pages":[{"title":"SDK","href":"/sdk/overview"}]}]},"basePath":"","title":"Edit study with AI agent - Versive","buildId":"dpl_9RFrWkXdFTJCytfx6jAofvAaEXr6","deploymentId":"dpl_9RFrWkXdFTJCytfx6jAofvAaEXr6","dynamics":["c2aa737661","2b790eda92","b0f84f53ff"],"chunks":["OpenApiReferenceProvider-BgGj2PGS.js","utils-BhNOqRKb.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-BAgRNUZo.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-CGkb0TPw.js","snippetPresets-ChLkL1a6.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-Ef10Jrbx.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-DlVCnjU8.js","shallow-BA55zJxQ.js","getApiPlaygroundDisplay-DR09dKtp.js","CodeSnippet-BZ8J8Kll.js","CodeSnippets-CcguVheG.js","Page-C7x-eUfk.js","getPastedJson-D5UqeqBp.js","icon-DpD0l99C.js","MethodPill-Wg2NXsp_.js","DuplicateIcon-CCSyX8lh.js","createIcon-C4Ukv9HX.js","DynamicMarkdown-RhjEuCHC.js","SectionHeading-DL1MykRq.js","axios-vUo_bRtp.js"]}