Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.userintuition.ai/llms.txt

Use this file to discover all available pages before exploring further.

The MCP server’s instructions field embeds this playbook so every client inherits the same discipline the in-app chat experience enforces. Follow these rules whenever you build or modify a study via the API.

​
Read before write

Always call get_assistant before calling update_assistant. Do the same for invites (get_invite before update_invite) and calls (get_call before update_call). The screener_questions field in update_assistant replaces the full list — it is not a merge or append. If you skip the read step, you will silently drop any screener questions that were already on the study.

​
Panel vs custom screeners

Two kinds of screener question coexist on a study and must both be preserved whenever you update screener_questions. Panel questions target the RepData panel. They require:
  • is_panel_question: true
  • A qualification_id sourced from list_available_panel_questions
Call list_available_panel_questions before composing a panel screener list to confirm the qualification_id values that are available. Custom questions are free-form text screeners you write yourself. They use:
  • is_panel_question: false
  • Your own question text — no qualification_id needed
When you read the existing screener_questions array and write it back, keep both panel and custom rows intact. Dropping one type when updating the other is a common mistake. Never add questions like “Do you consent to being recorded?” or “Are you willing to participate?” to the screener_questions list. Consent is collected outside the screener flow and is handled by the platform.

​
No auto-screeners on create

create_assistant should never automatically generate screener questions. Create the study with an empty or null screener list and only add screeners when the user explicitly asks for them, using a subsequent update_assistant call.

​
Mode = flags, not a column

Study mode is controlled by two boolean flags on the assistant record:
FlagDefaultEffect
enable_chatfalseText-chat interview instead of voice
enable_video_recordingfalseRecord video during the interview
Both flags default to false, which means voice-only. You can combine them — a study with enable_chat: true and enable_video_recording: true runs a chat interview that is video-recorded. There is no separate mode column.

​
Language

Set voice_config.language to an ISO 639-1 language code. Call list_available_languages to retrieve the list of codes the platform supports. Do not hard-code language strings.

​
Deletes are soft

delete_assistant, delete_invite, and delete_call do not permanently remove records. They set a deleted_at timestamp. Deleted studies, participants, and calls may be recoverable from the dashboard if you need to undo a deletion.