Projects

Projects are the top-level container for your research. Each project has one interview (the set of questions asked to participants) and a recruiting record that tracks participant targets and completion.

Automating question generation and project creation

If you'd rather not hand-write your interview questions, use Generate questions with AI to draft them, then create or update a project with the result. The flow differs slightly depending on whether you need stimuli media in the loop:

List projects

Example request

curl "https://external-api.prod.insightscompany.io/v1/projects" \
-H "x-api-key: <api_key>"

Example response

{
  "items": [
    {
      "created_at": "2026-06-01T10:00:00Z",
      "id": "b2c3d4e5-0000-0000-0000-000000000001",
      "recruiting": {
        "completed_participants": 4,
        "has_launched": true,
        "target_participants": 10,
        "type": "USER_INTERVIEWS"
      },
      "status": "IN_PROGRESS",
      "title": "Customer Onboarding Research"
    }
  ]
}

Create a project

Creates a new project, interview, and recruiting record in one call. You supply the questions directly — no AI generation step is required.

Example request

curl -X POST "https://external-api.prod.insightscompany.io/v1/projects" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
  "title": "Customer Onboarding Research",
  "type": "USER_INTERVIEW",
  "purpose": "Understand pain points in the onboarding flow",
  "research_objective": "Identify where users drop off and why",
  "intro_message": "Hi! Thanks for joining. This will take around 15 minutes.",
  "questions": [
    { "question": "Walk me through your first week using the product.", "probing_level": "high" },
    { "question": "What was the most confusing part of getting started?", "probing_level": "medium" },
    { "question": "What would have made onboarding easier?", "probing_level": "low" }
  ],
  "target_participants": 20,
  "recruiting_type": "INTERNAL",
  "languages": [
    { "language_name": "English", "accent": "en-US" }
  ],
  "interaction_modes": ["video", "audio"]
}'

Example response

Generate questions with AI

Drafts interview questions grounded in a research_objective you supply and your organisation's knowledge hub (company context, product summary, and — for CHURN studies — churn-specific context, pulled in automatically). Returns questions in the exact format POST /projects accepts, plus a suggested title and intro/end messages, so you can review and paste them straight into your create call.

Example request

curl -X POST "https://external-api.prod.insightscompany.io/v1/projects/generate-questions" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
  "research_objective": "Identify why customers churn within their first 90 days",
  "type": "CHURN"
}'

Request body

Example request — STIMULI study

Requires an existing project with stimuli already uploaded (see the STIMULI flow above).

curl -X POST "https://external-api.prod.insightscompany.io/v1/projects/generate-questions" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
  "research_objective": "Understand first reactions to the new homepage design",
  "type": "STIMULI",
  "project_id": "<project_id>"
}'

Example response

{
  "end_message": "Thanks so much for sharing your experience with us today.",
  "intro_message": "I'm an AI interviewer here to talk with you about your recent onboarding experience. If at any point you need me to repeat something, need more time to think or need to interrupt me - just let me know. Let's get started - can you walk me through the first time you set up your account?",
  "questions": [
    {
      "probing_level": "low",
      "question": "Can you walk me through the first time you set up your account?"
    },
    {
      "probing_level": "high",
      "question": "Can you tell me about a moment onboarding felt confusing?"
    }
  ],
  "suggested_title": "Customer Onboarding Research"
}

Notes

• This is synchronous — it calls an LLM and returns the drafted questions directly, typically within a few seconds.
• Nothing is saved automatically. Paste the returned questions (and optionally suggested_title as title, intro_message, end_message) into Create a project (new project) or Update project questions (existing draft).
• Returns 400 if type is STIMULI and project_id is omitted.
• Returns 404 if project_id is provided but doesn't belong to your organisation.
• Returns 502 if generation fails validation after retries (for example, too few distinct probing levels) — retry the request.
• Returns 503 if AI question generation isn't configured in this environment.
• Using Persona MCP instead? Its generate_questions tool works against an existing project and returns the same grounding as context for the connected AI client to draft questions with, then apply them by calling update_project directly — no separate generate/apply round trip needed.

Update project questions

Applies new questions, title, and/or intro/end messages to a draft project that hasn't launched yet — typically used to apply the output of Generate questions with AI onto a project you already created.

Example request

curl -X PATCH "https://external-api.prod.insightscompany.io/v1/projects/<project_id>" \
-H "x-api-key: <api_key>" \
-H "Content-Type: application/json" \
-d '{
  "questions": [
    { "question": "Can you walk me through the first time you set up your account?", "probing_level": "low" },
    { "question": "Can you tell me about a moment onboarding felt confusing?", "probing_level": "high" }
  ]
}'

Request body

At least one field is required.

Example response

{
  "end_message": "Thanks so much for sharing your experience with us today.",
  "id": "b2c3d4e5-0000-0000-0000-000000000001",
  "interview_id": "c3d4e5f6-0000-0000-0000-000000000002",
  "intro_message": "Hi! Thanks for joining. This will take around 15 minutes.",
  "questions": [
    {
      "probing_level": "low",
      "question": "Can you walk me through the first time you set up your account?"
    }
  ],
  "stimuli_cleared": false,
  "title": "Customer Onboarding Research"
}

Notes

• Only an unlaunched draft can be updated — returns 409 (not_editable) once the project has launched.
• If questions changes, any existing stimuli-to-question assignments are cleared (stimuli_cleared: true in the response) — re-assign them via POST /stimuli/assign.
• Returns 409 (conflict) if the guide contains survey questions, which must be edited through a different workflow.

Question probing levels

Each question has a probing_level that controls how many AI follow-up questions are asked before moving on:

Project types

For STIMULI projects, after creating the project you need to upload your media assets and assign them to questions before the project can be launched. See Stimuli for the upload and assignment workflow.

Interaction modes

interaction_modes controls which interview formats are offered to participants. At least one is required.

Single mode: the interview starts immediately in that format — participants see no format picker.

Multiple modes: participants choose their preferred format on the waiting screen before the interview begins.

All three modes use the same AI interviewer and question set — only the input/output channel differs. video and audio are transcribed in real time; chat is typed.

Recruiting types

Notes

• id is the project ID — needed to fetch completed Interviews, to launch the project, and to get embed snippets.
• interview_id is returned in the response for reference.
• target_participants sets a soft cap on completed interviews. It can be overridden at launch.
• recruiting_type defaults to INTERNAL if omitted.
• intro_message is required and shown to participants before the interview starts.
• end_message is optional and shown after the interview ends.
• languages is required and must contain at least one entry. Each entry takes language_name and accent — voice is assigned automatically.
• interaction_modes is required. Controls which interview formats participants can choose from.
• The project starts in STARTED status. Call Launch Project to make it live.