{"openapi":"3.1.0","info":{"title":"Versive Public API","description":"Organization-scoped REST API for creating and managing studies, interviews, questions, and research insights.","version":"1.0.0"},"paths":{"/api/v1/interviews/{id}":{"get":{"tags":["Interviews"],"summary":"Get Interview By Id","operationId":"get_interview_by_id_api_v1_interviews__id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Interviews"],"summary":"Update Interview","operationId":"update_interview_api_v1_interviews__id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInterviewReqV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/interviews":{"post":{"tags":["Interviews"],"summary":"Create Interview","operationId":"create_interview_api_v1_interviews_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInterviewReqV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Interviews"],"summary":"Get Interviews","description":"Fetch a single interview by vid, or list a study's interviews by study_id.\n\nMock and archived interviews are never included — this API behaves as if\nthey do not exist.","operationId":"get_interviews_api_v1_interviews_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"vid","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Vid"}},{"name":"study_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Study Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Page Size"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by interview status","title":"Status"},"description":"Filter by interview status"},{"name":"include_simulations","in":"query","required":false,"schema":{"type":"boolean","description":"Include AI-simulated interviews","default":true,"title":"Include Simulations"},"description":"Include AI-simulated interviews"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies":{"get":{"tags":["Studies"],"summary":"Get Studies","operationId":"get_studies_api_v1_studies_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Studies"],"summary":"Create Study","operationId":"create_study_api_v1_studies_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateStudyReqV1"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/studies/activity":{"get":{"tags":["Studies"],"summary":"Get Studies Activity","description":"Per-study response activity in one call: started/completed/simulated\ninterview counts and the latest interview time. Mock, archived, and\nnever-started 'open' rows are excluded, matching /studies/{id}/stats.","operationId":"get_studies_activity_api_v1_studies_activity_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_ids","in":"query","required":true,"schema":{"type":"string","description":"Comma-separated study ids (max 100)","title":"Study Ids"},"description":"Comma-separated study ids (max 100)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{id}":{"get":{"tags":["Studies"],"summary":"Get Study By Id","operationId":"get_study_by_id_api_v1_studies__id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Studies"],"summary":"Update Study","operationId":"update_study_api_v1_studies__id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStudyReqV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{id}/metrics":{"get":{"tags":["Studies"],"summary":"Get Study Metrics","description":"Raw response counts and the configured quota for a study.\n\nAll counts are real responses only (non-archived, non-mock). `complete`\n(status='closed') uses the same filter as quota enforcement. `in_progress`\ncounts interviews a participant has actually started but not finished; 'open'\nshells that were initialized but never started are excluded. `screened_out`\ncounts participants disqualified by screening logic — a distinct status, so\nit never overlaps `complete`. `quota` is passed through as stored — null when\nunset, or whatever integer the user configured (including 0). Callers derive\nquota-met / spots-remaining themselves from these values.","operationId":"get_study_metrics_api_v1_studies__id__metrics_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{id}/translate":{"post":{"tags":["Studies"],"summary":"Translate Study","operationId":"translate_study_api_v1_studies__id__translate_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{id}/translations":{"get":{"tags":["Studies"],"summary":"Get Study Translations","operationId":"get_study_translations_api_v1_studies__id__translations_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","title":"Id"}},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional language to filter by; omit to return all languages","title":"Language"},"description":"Optional language to filter by; omit to return all languages"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/ai-edit":{"post":{"tags":["Studies"],"summary":"Ai Edit Study","operationId":"ai_edit_study_api_v1_studies__study_id__ai_edit_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIEditRequestV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AIEditResponseV1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/agent":{"post":{"tags":["Studies"],"summary":"Agent Edit Study","description":"Execute AI-powered study editing.\n\nReturns the agent's mutations alongside the materialized post-edit state.\nBy default (`auto_save=True`), changes are persisted to the database with\nautomatic rollback on failure — same behavior as before this endpoint\nstarted returning mutations. Pass `auto_save=false` to preview the edits\nwithout writing; callers can then POST the mutations to `/agent/apply`\nwhen ready to commit.\n\n`model` selects the agent's underlying LLM:\n- \"smart\" (default): gpt-5.6-sol — highest quality on complex multi-step\n  edits, slower and more expensive.\n- \"fast\": gpt-5.6-terra — faster and cheaper. Good for simple\n  instructions or preview-and-revise flows.","operationId":"agent_edit_study_api_v1_studies__study_id__agent_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentEditRequestV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentEditResponseV1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/agent/apply":{"post":{"tags":["Studies"],"summary":"Agent Apply Mutations","description":"Persist a list of agent mutations to the database.\n\nAccepts the `mutations` payload returned by POST /agent, applies them\nsequentially with rollback on failure, and returns the resulting study\nstate.","operationId":"agent_apply_mutations_api_v1_studies__study_id__agent_apply_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplyMutationsRequestV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentEditResponseV1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/stats":{"get":{"tags":["Study Results"],"summary":"Get Study Stats","description":"Completion funnel for a study.\n\nPer-question answer aggregates live on\nGET /{study_id}/questions/{question_id}/stats — a different shape entirely.","operationId":"get_study_stats_api_v1_studies__study_id__stats_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}},{"name":"include_simulations","in":"query","required":false,"schema":{"type":"boolean","description":"Include AI-simulated interviews","default":true,"title":"Include Simulations"},"description":"Include AI-simulated interviews"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/questions/{question_id}/stats":{"get":{"tags":["Study Results"],"summary":"Get Study Question Stats","description":"Answer aggregates for one quantitative question: the same numbers the\ndashboard charts show. Unsupported question types return 400.","operationId":"get_study_question_stats_api_v1_studies__study_id__questions__question_id__stats_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}},{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}},{"name":"include_simulations","in":"query","required":false,"schema":{"type":"boolean","description":"Include AI-simulated interviews","default":true,"title":"Include Simulations"},"description":"Include AI-simulated interviews"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/export":{"get":{"tags":["Study Results"],"summary":"Export Study Data","description":"CSV of interview responses: one row per interview, one column per question.","operationId":"export_study_data_api_v1_studies__study_id__export_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Page Size"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by interview status; omit for all active","title":"Status"},"description":"Filter by interview status; omit for all active"},{"name":"include_simulations","in":"query","required":false,"schema":{"type":"boolean","description":"Include AI-simulated interviews","default":true,"title":"Include Simulations"},"description":"Include AI-simulated interviews"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/folders":{"get":{"tags":["Folders"],"summary":"Get Folders","operationId":"get_folders_api_v1_folders_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"HTTPBearer":[]}]},"post":{"tags":["Folders"],"summary":"Create Folder","operationId":"create_folder_api_v1_folders_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFolderReqV1"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/questions":{"get":{"tags":["Questions"],"summary":"Get Questions","operationId":"get_questions_api_v1_questions_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"query","required":true,"schema":{"type":"string","description":"ID of the study to retrieve questions for","title":"Study Id"},"description":"ID of the study to retrieve questions for"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/questions/batch":{"post":{"tags":["Questions"],"summary":"Create Questions Batch","operationId":"create_questions_batch_api_v1_questions_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatchQuestionsReqV1"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBatchQuestionsResponseV1"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/questions/batch-delete":{"post":{"tags":["Questions"],"summary":"Delete Questions Batch","description":"Soft-delete a validated set of questions in one database statement.","operationId":"delete_questions_batch_api_v1_questions_batch_delete_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteBatchQuestionsReqV1"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/questions/{question_id}":{"put":{"tags":["Questions"],"summary":"Update Question","operationId":"update_question_api_v1_questions__question_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Questions"],"summary":"Delete Question","operationId":"delete_question_api_v1_questions__question_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"question_id","in":"path","required":true,"schema":{"type":"string","title":"Question Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/question-logic":{"get":{"tags":["Question Logic"],"summary":"Get Question Logic","operationId":"get_question_logic_api_v1_question_logic_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"question_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter logic by a single question","title":"Question Id"},"description":"Filter logic by a single question"},{"name":"study_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter logic by a study","title":"Study Id"},"description":"Filter logic by a study"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional language filter; omit for all languages","title":"Language"},"description":"Optional language filter; omit for all languages"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Question Logic"],"summary":"Create Question Logic","operationId":"create_question_logic_api_v1_question_logic_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQuestionLogicReqV1"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/question-logic/{logic_id}":{"put":{"tags":["Question Logic"],"summary":"Update Question Logic","operationId":"update_question_logic_api_v1_question_logic__logic_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"logic_id","in":"path","required":true,"schema":{"type":"string","title":"Logic Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQuestionLogicReqV1"}}}},"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"tags":["Question Logic"],"summary":"Delete Question Logic","operationId":"delete_question_logic_api_v1_question_logic__logic_id__delete","security":[{"HTTPBearer":[]}],"parameters":[{"name":"logic_id","in":"path","required":true,"schema":{"type":"string","title":"Logic Id"}}],"responses":{"204":{"description":"Successful Response"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/question-groups":{"get":{"tags":["Question Groups"],"summary":"Get Question Groups","operationId":"get_question_groups_api_v1_question_groups_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"query","required":true,"schema":{"type":"string","description":"ID of the study whose groups to retrieve","title":"Study Id"},"description":"ID of the study whose groups to retrieve"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Question Groups"],"summary":"Create Question Group","operationId":"create_question_group_api_v1_question_groups_post","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQuestionGroupReqV1"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/question-groups/{group_id}":{"put":{"tags":["Question Groups"],"summary":"Update Question Group","operationId":"update_question_group_api_v1_question_groups__group_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQuestionGroupReqV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/question-groups/move-questions":{"post":{"tags":["Question Groups"],"summary":"Move Questions To Group","operationId":"move_questions_to_group_api_v1_question_groups_move_questions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveQuestionsToGroupReqV1"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/api/v1/question-groups/{group_id}/remove":{"post":{"tags":["Question Groups"],"summary":"Remove Question Group","operationId":"remove_question_group_api_v1_question_groups__group_id__remove_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"group_id","in":"path","required":true,"schema":{"type":"string","title":"Group Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemoveQuestionGroupReqV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/insights":{"get":{"tags":["Insights"],"summary":"Get Insights","operationId":"get_insights_api_v1_insights_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"interview_id","in":"query","required":true,"schema":{"type":"string","description":"Interview ID to retrieve transcript summary insight for","title":"Interview Id"},"description":"Interview ID to retrieve transcript summary insight for"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/translated-questions":{"get":{"tags":["Translated Questions"],"summary":"Get Translated Questions","operationId":"get_translated_questions_api_v1_translated_questions_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Study to read translated questions for","title":"Study Id"},"description":"Study to read translated questions for"},{"name":"question_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Question to read translated questions for","title":"Question Id"},"description":"Question to read translated questions for"},{"name":"language","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Optional language filter; omit for all languages","title":"Language"},"description":"Optional language filter; omit for all languages"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/translated-questions/{translated_question_id}":{"get":{"tags":["Translated Questions"],"summary":"Get Translated Question","operationId":"get_translated_question_api_v1_translated_questions__translated_question_id__get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"translated_question_id","in":"path","required":true,"schema":{"type":"string","title":"Translated Question Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Translated Questions"],"summary":"Update Translated Question","operationId":"update_translated_question_api_v1_translated_questions__translated_question_id__put","security":[{"HTTPBearer":[]}],"parameters":[{"name":"translated_question_id","in":"path","required":true,"schema":{"type":"string","title":"Translated Question Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTranslatedQuestionReqV1"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/studies/{study_id}/available-references":{"get":{"tags":["References"],"summary":"List valid question mention templates","description":"List the questions a question can reference, with insertable mention templates.\n\nMirrors the \"@\" picker in the Versive study editor: returns each previous,\ntaggable question along with its full-answer reference and any property\nreferences, each carrying the exact ``{{Q:...}}`` template string to insert.\nInsert the returned ``template`` verbatim into the destination question's\n``content``.\n\nFull-answer references (``{{Q:<id>}}``) are available for textInput,\nshortText, multipleChoice, matrixRatingScale, ranking, allocation, and\ncardSort. Structured property references are additionally available for:\n\n- matrixRatingScale: ``ratingForItem[index]``\n- ranking: ``rankOfOption[index]`` and ``optionAtRank[index]``\n- allocation: ``allocationForItem[index]``\n- cardSort: ``categoryForCard[index]`` and ``cardsInCategory[index]``\n\nProperty indices are zero-based. textInput, shortText, and multipleChoice\nexpose only the full answer.\n\nOnly non-sensitive, author-owned fields are exposed (question IDs are\nintentionally included because templates require them).","operationId":"get_available_references_api_v1_studies__study_id__available_references_get","security":[{"HTTPBearer":[]}],"parameters":[{"name":"study_id","in":"path","required":true,"schema":{"type":"string","title":"Study Id"}},{"name":"before_question_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Only return questions that appear before this question. Use when editing an existing question.","title":"Before Question Id"},"description":"Only return questions that appear before this question. Use when editing an existing question."},{"name":"before_display_order","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Only return questions with a display_order strictly less than this value. Use when composing a not-yet-created question.","title":"Before Display Order"},"description":"Only return questions with a display_order strictly less than this value. Use when composing a not-yet-created question."}],"responses":{"200":{"description":"Referenceable earlier questions and exact insertable mention templates.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableReferencesResponseV1"},"example":{"references":[{"question_id":"matrix-question-id","display_order":1,"type":"matrixRatingScale","content":"Rate each part of the experience","label":"Q2","available_references":[{"kind":"fullAnswer","label":"Q2","template":"{{Q:matrix-question-id}}"},{"kind":"property","label":"Q2.ratingForItem[1]","template":"{{Q:matrix-question-id.ratingForItem[0]}}","property_name":"ratingForItem","property_index":0,"option":"Speed"}]}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AIEditRequestV1":{"properties":{"current_message":{"type":"string","title":"Current Message"},"questions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Questions"},"language":{"type":"string","title":"Language"}},"type":"object","required":["current_message","questions","language"],"title":"AIEditRequestV1"},"AIEditResponseV1":{"properties":{"questions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Questions"},"change_log":{"additionalProperties":true,"type":"object","title":"Change Log"},"deleted_questions":{"items":{"type":"string"},"type":"array","title":"Deleted Questions"}},"type":"object","required":["questions","change_log","deleted_questions"],"title":"AIEditResponseV1"},"AgentEditRequestV1":{"properties":{"message":{"type":"string","title":"Message"},"auto_save":{"type":"boolean","title":"Auto Save","default":true},"model":{"type":"string","enum":["fast","smart"],"title":"Model","default":"smart"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","description":"Optional target language name or code for generated or rewritten participant-facing content."}},"type":"object","required":["message"],"title":"AgentEditRequestV1","description":"Request for public v1 agent endpoint."},"AgentEditResponseV1":{"properties":{"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"mutations":{"items":{"$ref":"#/components/schemas/MutationV1"},"type":"array","title":"Mutations"},"questions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Questions"},"logic":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Logic"},"study_settings":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Study Settings"},"broken_mentions":{"items":{"$ref":"#/components/schemas/BrokenMentionV1"},"type":"array","title":"Broken Mentions","description":"Invalid {{Q:...}} references present in the post-edit study state. Empty when all question mentions resolve correctly. Entries with newly_broken=true were broken by this edit."},"question_groups":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Question Groups"},"routing_nodes":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Routing Nodes"},"routing_branches":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Routing Branches"}},"type":"object","required":["mutations","questions","logic"],"title":"AgentEditResponseV1","description":"Response from public v1 agent endpoint.\n\nReturns the agent's mutations alongside the materialized post-edit state.\nCustomers can either use the materialized fields directly, or POST the\nmutations to /agent/apply to persist them.\n\nEach question in `questions` carries a `mentions` array resolving its\n`{{Q:...}}` references to `{placeholder, referenced_question_id, label,\ntype, property_name, property_index, valid, error}`, so consumers can\nrender and understand references without parsing tokens. `broken_mentions`\nlists any invalid references in the post-edit state (entries with\n`newly_broken=true` were broken by this edit). Randomizer edits are\nmaterialized in `routing_nodes`, `routing_branches`, and the routing\nownership fields on questions and question groups."},"ApplyMutationsRequestV1":{"properties":{"mutations":{"items":{"$ref":"#/components/schemas/MutationV1"},"type":"array","title":"Mutations"}},"type":"object","required":["mutations"],"title":"ApplyMutationsRequestV1","description":"Request for POST /api/v1/studies/{study_id}/agent/apply."},"AvailableReferenceItemV1":{"properties":{"kind":{"type":"string","enum":["fullAnswer","property"],"title":"Kind","description":"Whether the template inserts the complete answer or one structured property/option response."},"label":{"type":"string","title":"Label","description":"Human-readable label for an authoring interface."},"template":{"type":"string","title":"Template","description":"Exact token to insert into the destination question's content. Use this value verbatim instead of constructing a token manually.","examples":["{{Q:question-id.ratingForItem[0]}}"]},"property_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Property Name","description":"Structured-answer selector for property references. Supported selectors: matrixRatingScale=ratingForItem; ranking=rankOfOption or optionAtRank; allocation=allocationForItem; cardSort=categoryForCard or cardsInCategory. Null for a full-answer reference.","examples":["ratingForItem"]},"property_index":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Property Index","description":"Zero-based index into the source question's options, categories, or rank positions. Null for a full-answer reference.","examples":[0]},"option":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Option","description":"The option, category, or rank-position label selected by this property reference. Null for a full-answer reference.","examples":["Speed"]}},"type":"object","required":["kind","label","template"],"title":"AvailableReferenceItemV1","description":"A single insertable reference (full answer or a specific property)."},"AvailableReferencesResponseV1":{"properties":{"references":{"items":{"$ref":"#/components/schemas/ReferenceableQuestionV1"},"type":"array","title":"References","description":"Earlier, active questions that can be mentioned from the requested study position, ordered by display_order."}},"type":"object","required":["references"],"title":"AvailableReferencesResponseV1"},"BrokenMentionV1":{"properties":{"question_id":{"type":"string","title":"Question Id"},"placeholder":{"type":"string","title":"Placeholder"},"error":{"type":"string","title":"Error"},"newly_broken":{"type":"boolean","title":"Newly Broken"}},"type":"object","required":["question_id","placeholder","error","newly_broken"],"title":"BrokenMentionV1","description":"A ``{{Q:...}}`` reference that is invalid in the post-edit study state.\n\nSurfaced so API callers can detect when an agent edit broke an existing\nmanual question mention (e.g. by deleting, reordering, or changing the\nprops of a referenced question)."},"CreateBatchQuestionsReqV1":{"properties":{"questions":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Questions","description":"Questions to create or update. A question's content may include exact {{Q:...}} mention templates returned by GET /api/v1/studies/{study_id}/available-references."}},"type":"object","required":["questions"],"title":"CreateBatchQuestionsReqV1"},"CreateBatchQuestionsResponseV1":{"properties":{"created_question_ids":{"items":{"type":"string"},"type":"array","title":"Created Question Ids"},"updated_question_ids":{"items":{"type":"string"},"type":"array","title":"Updated Question Ids"}},"type":"object","required":["created_question_ids","updated_question_ids"],"title":"CreateBatchQuestionsResponseV1"},"CreateFolderReqV1":{"properties":{"name":{"type":"string","title":"Name"},"access_policy":{"anyOf":[{"type":"string","enum":["FULL_ACCESS","CAN_EDIT","CAN_EDIT_SURVEY_ONLY","CAN_VIEW","INVITE_ONLY"]},{"type":"null"}],"title":"Access Policy","default":"FULL_ACCESS"}},"type":"object","required":["name"],"title":"CreateFolderReqV1"},"CreateInterviewReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"language":{"type":"string","title":"Language","default":"English"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"}},"type":"object","required":["study_id"],"title":"CreateInterviewReqV1"},"CreateQuestionGroupReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"title":{"type":"string","minLength":1,"title":"Title"},"parent_question_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Parent Question Group Id"},"is_randomize":{"type":"boolean","title":"Is Randomize","default":false}},"type":"object","required":["study_id","title"],"title":"CreateQuestionGroupReqV1"},"CreateQuestionLogicReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"question_id":{"type":"string","title":"Question Id"},"operation":{"type":"string","enum":["==","<=","<",">",">=","COUNT_LT","INCLUDES","ALWAYS","INCLUDE_RESPONSE_IN_NEXT_QUESTION","SMART_CONDITION"],"title":"Operation"},"comparison_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comparison Value"},"comparison_value_type":{"type":"string","enum":["string","int","smart_condition"],"title":"Comparison Value Type"},"next_question_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Question Id"},"next_question_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Question Group Id"},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url"},"end_interview":{"type":"boolean","title":"End Interview","default":false},"action_type":{"type":"string","enum":["end_interview","redirect_url","next_question_id","screen_out","move_to_question_group"],"title":"Action Type"},"language":{"type":"string","title":"Language","default":"English"}},"type":"object","required":["study_id","question_id","operation","comparison_value_type","action_type"],"title":"CreateQuestionLogicReqV1"},"CreateStudyReqV1":{"properties":{"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"type":{"type":"string","title":"Type","default":"VERSIVE_STUDY"},"mode":{"type":"string","title":"Mode","default":"TEXT_AND_VOICE"},"welcome_message":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Welcome Message"},"thank_you_message":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Thank You Message"},"screen_out_message":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Screen Out Message"},"folder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Id"},"insights":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Insights"},"access_policy":{"type":"string","enum":["FULL_ACCESS","CAN_EDIT","CAN_EDIT_SURVEY_ONLY","CAN_VIEW","INVITE_ONLY"],"title":"Access Policy","default":"FULL_ACCESS"}},"type":"object","required":["title"],"title":"CreateStudyReqV1"},"DeleteBatchQuestionsReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"question_ids":{"items":{"type":"string"},"type":"array","title":"Question Ids"}},"type":"object","required":["study_id","question_ids"],"title":"DeleteBatchQuestionsReqV1"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"MoveQuestionsToGroupReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"question_ids":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Question Ids"},"question_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Question Group Id"}},"type":"object","required":["study_id","question_ids"],"title":"MoveQuestionsToGroupReqV1"},"MutationV1":{"properties":{"id":{"type":"string","title":"Id"},"entity_type":{"type":"string","enum":["question","logic_rule","study_settings","study_messages","question_group","routing_composite"],"title":"Entity Type"},"operation":{"type":"string","enum":["create","update","delete","reorder"],"title":"Operation"},"entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entity Id"},"before":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Before"},"after":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"After"},"timestamp":{"type":"number","title":"Timestamp"}},"type":"object","required":["id","entity_type","operation","timestamp"],"title":"MutationV1","description":"A single change produced by the agent. Opaque payload for /agent/apply."},"ReferenceableQuestionV1":{"properties":{"question_id":{"type":"string","title":"Question Id","description":"Source question ID used in mention templates."},"display_order":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Display Order","description":"Zero-based position of the source question in the study."},"type":{"type":"string","title":"Type","description":"Source question type. Referenceable types are textInput, shortText, multipleChoice, matrixRatingScale, ranking, allocation, and cardSort."},"content":{"type":"string","title":"Content","description":"Source question content."},"label":{"type":"string","title":"Label","description":"Human-readable question label, such as Q2."},"available_references":{"items":{"$ref":"#/components/schemas/AvailableReferenceItemV1"},"type":"array","title":"Available References","description":"Valid insertable templates for this source question. Every source has a fullAnswer item. matrixRatingScale, ranking, allocation, and cardSort also include property items; textInput, shortText, and multipleChoice do not."}},"type":"object","required":["question_id","type","content","label","available_references"],"title":"ReferenceableQuestionV1","description":"A previous question that can be referenced, plus its valid references.\n\nOnly non-sensitive, author-owned fields are exposed. Question IDs are\nintentionally included because they are required to build mention\ntemplates."},"RemoveQuestionGroupReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"mode":{"type":"string","enum":["ungroup","delete"],"title":"Mode","default":"ungroup"}},"type":"object","required":["study_id"],"title":"RemoveQuestionGroupReqV1"},"UpdateInterviewReqV1":{"properties":{"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","title":"UpdateInterviewReqV1"},"UpdateQuestionGroupReqV1":{"properties":{"study_id":{"type":"string","title":"Study Id"},"title":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Title"},"is_randomize":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Randomize"}},"type":"object","required":["study_id"],"title":"UpdateQuestionGroupReqV1"},"UpdateQuestionLogicReqV1":{"properties":{"operation":{"anyOf":[{"type":"string","enum":["==","<=","<",">",">=","COUNT_LT","INCLUDES","ALWAYS","INCLUDE_RESPONSE_IN_NEXT_QUESTION","SMART_CONDITION"]},{"type":"null"}],"title":"Operation"},"comparison_value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Comparison Value","default":""},"comparison_value_type":{"anyOf":[{"type":"string","enum":["string","int","smart_condition"]},{"type":"null"}],"title":"Comparison Value Type"},"next_question_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Question Id","default":""},"next_question_group_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Question Group Id","default":""},"redirect_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Url","default":""},"end_interview":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"End Interview","default":false},"action_type":{"anyOf":[{"type":"string","enum":["end_interview","redirect_url","next_question_id","screen_out","move_to_question_group"]},{"type":"null"}],"title":"Action Type"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language","default":"English"}},"type":"object","title":"UpdateQuestionLogicReqV1"},"UpdateStudyReqV1":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"access_policy":{"anyOf":[{"type":"string","enum":["FULL_ACCESS","CAN_EDIT","CAN_EDIT_SURVEY_ONLY","CAN_VIEW","INVITE_ONLY"]},{"type":"null"}],"title":"Access Policy"},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config"},"welcome_message":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Welcome Message"},"thank_you_message":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Thank You Message"},"screen_out_message":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Screen Out Message"},"folder_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Folder Id"},"status":{"anyOf":[{"type":"string","enum":["published","paused","archived"]},{"type":"null"}],"title":"Status"},"mode":{"anyOf":[{"type":"string","enum":["TEXT_ONLY","TEXT_AND_VOICE","VOICE_ONLY","VOICE_WITH_PREVIEW","VIDEO","VOICE_AND_VIDEO"]},{"type":"null"}],"title":"Mode"},"quota":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Quota"},"pause_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Pause Url"}},"type":"object","title":"UpdateStudyReqV1"},"UpdateTranslatedQuestionReqV1":{"properties":{"content":{"type":"string","title":"Content"}},"type":"object","required":["content"],"title":"UpdateTranslatedQuestionReqV1"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}