{"site":{"name":"Koji","description":"AI-native customer research platform that helps teams conduct, analyze, and synthesize customer interviews at scale.","url":"https://www.koji.so","contentTypes":["blog","documentation"],"lastUpdated":"2026-11-08T22:03:05.503Z"},"content":[{"type":"documentation","id":"1bd7d712-c17b-420e-8cf1-538169ed7fab","slug":"user-research-api-guide","title":"User Research API: Embed AI Interviews into Any Product or Workflow","url":"https://www.koji.so/docs/user-research-api-guide","summary":"The Koji User Research API exposes four REST endpoints (start, message, complete and read) plus an embed that posts browser events, letting developers run AI-moderated text and voice interviews from any backend. It is included on the Interviews and Enterprise plans, along with API keys and the MCP connector. Each API key belongs to one study and carries its own permissions. The start endpoint takes an optional respondent object (external_id, display_name, metadata), a mode and a locale, and returns an interview ID and session token. The API supports adaptive follow-up probing, 6 structured question types and an automatic 1 to 5 quality score per interview. Usage is billed in credits at 1 euro each (1 for text, 3 for voice, 5 for a report refresh), and interviews that fail the quality check are not charged. Koji has no outbound webhooks yet, so completion is detected by polling the read endpoint or forwarding the embed's completion event. The MCP connector exposes study management to AI agents such as Claude. Common patterns include in-product cancel-flow interviews, PLG onboarding research and research run by an AI agent.","content":"## The Bottom Line\n\nA **User Research API** lets you trigger AI-moderated user interviews from your own backend code instead of a SaaS dashboard. Koji exposes a headless interview API: start an interview, exchange messages, complete it, and read the analyzed transcript back. It is included on the **Interviews** and **Enterprise** plans. There are no outbound webhooks yet, so your backend polls the read endpoint or listens for the embed widget's browser events. Either way you can put conversational research anywhere a customer touchpoint exists: an in-product onboarding flow, a churn cancellation screen, a post-purchase email, a Discord bot, or an internal data pipeline.\n\nThe core primitives are four REST endpoints plus an embed that posts completion events to the parent page. With these you can run a full customer research conversation programmatically: the AI interviewer adapts to each participant, asks follow-up questions, and your backend reads quality-scored transcripts and structured answers as soon as analysis finishes.\n\nThis guide is the entry point. If you're evaluating whether a research platform fits your stack, or you've outgrown survey APIs that only POST form responses, this article shows how Koji's API differs and where to go next.\n\n## Why a User Research API Exists\n\nMost research tools assume a researcher logs into a dashboard, sends a link, and reads the results manually. That model breaks at three common moments:\n\n1. **In-product moments matter more than scheduled studies.** The best feedback comes from a user mid-task, not a user three weeks later trying to remember what frustrated them. A research API lets you trigger an interview the moment a user hits a meaningful trigger (clicks \"Cancel subscription\", finishes onboarding, downgrades).\n2. **Product-led growth teams want every signup interviewed.** When you're onboarding hundreds of users a week, sending them all the same Typeform isn't research, it's a survey. An API lets you start an AI interview per qualified signup and feed the structured output into your CRM.\n3. **AI-native teams want research data as a feed.** You want themes, quotes, and structured answers landing in your data warehouse, Slack, or your own LLM agent, not a PDF.\n\nA real user research API answers all three. Survey tools like SurveyMonkey or Qualtrics have APIs for forms and responses, not for running conversational interviews.\n\n## The Core API Primitives\n\n### 1. Headless Interview Endpoints\n\nThe Koji REST API exposes four conversation endpoints under `/api/v1`:\n\n- **`POST /api/v1/interviews/start`**: Open an interview session. The study comes from the API key, so you don't pass a study ID. The body takes an optional `respondent` object (`external_id`, `display_name`, and free-form `metadata`), plus `mode` (`text` or `voice`) and `locale`. It returns an `interview_id`, a `session_token`, and the first AI message.\n- **`POST /api/v1/interviews/{id}/message`**: Send a participant message with the `X-Session-Token` header and receive the next AI response. The AI decides whether to ask a follow-up, move to the next question, or wrap up.\n- **`POST /api/v1/interviews/{id}/complete`**: Mark the interview complete and trigger analysis. The transcript is quality-scored and themes are extracted asynchronously.\n- **`GET /api/v1/interviews/{id}`**: Read the transcript, the respondent (including your `external_id`), and the analysis: quality score, structured answers, and themes.\n\nAuthentication is via Bearer tokens. CORS is permissive on these endpoints, so browser-based callers work without a proxy.\n\n![Koji Integration API page listing REST endpoints for interviews and outbound calls](/email/shots/shot-endpoints.jpg \"The Integration API page lists the base URL and every endpoint your key can call\")\n\n### 2. The Embed\n\nIf you'd rather not implement the conversation loop yourself, the study's **Integrate** screen gives you an iframe embed (plus React and headless options) that renders the interview UI inside your app. Drop it into a modal, a sidebar, or a dedicated page. It handles text, voice, and the structured-question widgets (buttons, sliders, radio, checkbox, drag-to-rank) automatically, and it posts events such as `koji:interview_started` and `koji:interview_completed` to the parent page.\n\n### 3. Completion Signals for Near-Real-Time Pipelines\n\nKoji has no outbound webhooks yet, so there is no URL to register and nothing signed arriving at your server. Two patterns give you the same outcome:\n\n- **Poll the read endpoint.** Store each `interview_id` when you start an interview, then have a scheduled job call `GET /api/v1/interviews/{id}` and act when `status` is `completed` and `analysis` is present, which is when the quality score, themes and structured answers are all populated.\n- **Forward the embed event.** If the interview runs in the embed, the respondent's browser posts `koji:interview_completed` to the parent page. Forward it to your backend as a fast path, and keep the poller as the source of truth: the event only fires while the tab is open.\n\nThis is how teams build \"research-aware\" automations: post every interview transcript to a Slack channel, sync structured NPS answers into HubSpot, open a Linear ticket when a churn-risk theme appears, or feed insights into a Claude agent that drafts PRDs. The trigger is your own job, not a Koji callback. See [Webhook Setup](/docs/webhook-setup) for working code.\n\n### 4. CRM and CSV Import\n\nTo interview people you already know, import them as a CSV in the dashboard (or through the MCP connector's respondent import). Each respondent gets a personalized interview link with a unique token, so you can target named accounts, send 1:1 invites, and tie results back to a contact record in your CRM. When you need people you do not have, the same study can also be filled from Koji's built-in panel: open Panel recruit in the dashboard, describe the audience, approve the price per completed interview in credits, and those interviews land in the same study.\n\n## Authentication\n\nKoji uses standard Bearer-token authentication:\n\n```\nAuthorization: Bearer pk_live_<your-api-key>\n```\n\nEach API key belongs to one study and carries a set of permissions: start interviews, send messages, complete interviews, read interview data, and (if you enable them) schedule and read outbound calls. You can restrict a key to allowed origins for browser use, see when it was last used, and revoke it at any time.\n\n![Koji API keys settings listing masked keys with permissions, allowed domains and last used dates](/email/shots/shot-api-keys.jpg \"Each key shows its permissions, allowed domains and when it was last used\")\n\nRequests are rate-limited per key. If you go over, you get a `429 Too Many Requests` response with a retry time, so back off and try again.\n\n## Plans, Pricing and Credits\n\nThe headless API, API keys and the MCP connector are included on the **Interviews** and **Enterprise** plans. On other plans the API answers with a 403 that asks for an Interviews plan or higher. Voice interviews, through the API or anywhere else, are also an Interviews and Enterprise feature. Usage is credit-based and identical to dashboard interviews, with credits at €1:\n\n- **Text interview**: 1 credit\n- **Voice interview**: 3 credits\n- **Report refresh**: 5 credits\n- **Quality check**: interviews that fail Koji's quality check don't consume credits\n\nThere are no per-seat or per-call API surcharges. When your plan's credits run low you can buy credit packs, and you can turn on auto-reload with a monthly cap if you want top-ups to happen on their own.\n\nFor team-wide API deployments (multiple products embedding interviews, SSO/SAML, isolated infrastructure, and a signed DPA), the [**Enterprise plan**](/enterprise) adds the controls procurement asks for, with custom committed credit volume and invoicing.\n\nCompared with survey APIs that charge per response or per question, Koji is simple: a research-grade text interview costs 1 credit, and a conversation that fails the quality check is never charged.\n\n## Architecture Patterns\n\nHere's how typical implementations look.\n\n### Pattern A: In-Product Cancel Flow\n\nA SaaS product wants to interview every user who clicks \"Cancel my subscription.\" The cancel button opens a modal in the product's own UI, and the backend starts a Koji interview with the user ID as `respondent.external_id` and plan and tenure in `metadata`. The AI runs a 3-minute interview asking why they're leaving, what almost stopped them, and what would bring them back. The transcript is analyzed, a poller reads it back and, if the theme \"missing feature\" appears, posts the quote to the product team's Slack.\n\n### Pattern B: PLG Onboarding Research at Scale\n\nA developer-tools company wants to interview every signup that completes the tutorial. A daily job picks out qualified signups and imports them as respondents, which gives each one a personalized interview link, then sends the links by email. A second scheduled job polls the read endpoint and routes finished transcripts into the company's warehouse (BigQuery) tagged with the user's plan and traffic source. The product manager queries the table for emerging themes by cohort.\n\n### Pattern C: Research Run by an AI Agent\n\nA founder builds an AI agent in Claude that supervises customer research. The agent calls Koji over MCP (Model Context Protocol) to list and read studies, draft new ones, update briefs, publish, import respondents, generate and publish reports, and export data. From the founder's perspective, customer research is a tool the AI uses. Koji's MCP connector has fifteen tools and covers study management, while the REST API covers running interviews and calls.\n\n### Pattern D: Embedding Research in a Mobile App\n\nA mobile team wants in-app feedback that goes deeper than NPS. They put the embed inside a sheet view, with voice turned on. Users speak into their phone, and the AI converses, probes, and wraps up in a couple of minutes. The team sees themes ranked by frequency, quality-scored, with verbatim quotes, all without anyone scheduling a call.\n\n## How Koji's User Research API Compares\n\n| Capability | Survey APIs (Typeform/SurveyMonkey) | Recording APIs (UserTesting/Maze) | **Koji User Research API** |\n|---|---|---|---|\n| Conversational AI interviews | No (static form) | Recording-based | Yes (text + voice) |\n| Adaptive follow-up probing | No | Manual moderator only | Yes, with follow-up settings per question |\n| Structured + qualitative output | Form fields only | Manual tagging | 6 structured types + free-form transcripts |\n| Per-interview quality scoring | No | Manual review | Automatic 1 to 5 score |\n| Completion signal on transcript analysis | Limited | Limited | Read endpoint plus embed events (no outbound webhooks yet) |\n| Voice mode programmatically | No | Recording, not conversational | Yes (3 credits/interview) |\n| Embed | Form embeds | Iframe recordings | Full interview embed with branding |\n| Plan needed for the API | Varies | Enterprise only typically | Interviews or Enterprise, 10 free signup credits to try Koji first |\n\nIn short: survey APIs collect answers, recording APIs save videos, and Koji's API runs conversations.\n\n## Getting Started\n\n1. **Create a workspace.** Sign up at koji.so. You get 10 free credits to try Koji in the dashboard. API access needs the Interviews or Enterprise plan.\n2. **Build your first study in the dashboard.** It's easier to validate the brief in the UI before going headless. Add structured questions if you want chartable answers.\n3. **Generate an API key.** Open the study's Integrate screen (or API keys in workspace settings) and create a key. Copy it once: it's only displayed at creation time.\n4. **Test `POST /api/v1/interviews/start`.** Use cURL with your key and an optional `respondent` object. You'll get an `interview_id`, a `session_token` and the first AI greeting.\n5. **Loop messages.** Send a participant reply to `POST /api/v1/interviews/{id}/message` with the session token and read the AI's next message.\n6. **Complete and read results.** Call `POST /api/v1/interviews/{id}/complete` to finalize. Analysis runs asynchronously. Poll `GET /api/v1/interviews/{id}` for the quality score and structured answers, or forward the embed's completion event if the interview runs in the embed.\n\nFor production, run the poller on a schedule. The full API specification, including request and response schemas, is in [Headless API Overview](/docs/headless-api-overview).\n\n## Frequently Asked Questions\n\n**Can I use the API on the free plan?** No. The headless API, API keys and the MCP connector are included on the Interviews and Enterprise plans, and outbound webhooks are not available yet. New accounts get 10 free credits to try text interviews in the dashboard first.\n\n**How do I authenticate?** Bearer tokens: `Authorization: Bearer pk_live_<key>`. Each key belongs to one study, has its own permissions, and can be revoked.\n\n**Is there a rate limit?** Yes, per key. Going over returns 429 with a retry time. Most production workloads stay well below it.\n\n**Are voice interviews supported via the API?** Yes, on the Interviews and Enterprise plans. Start the interview with `mode` set to `voice` and the response includes voice session credentials, or let the embed handle audio for you. Voice interviews cost 3 credits each.\n\n**How do I know when an interview has finished?** There are no outbound webhooks yet, so there is nothing to register or verify. Poll `GET /api/v1/interviews/{id}` from a scheduled job and act when `status` is `completed` and `analysis` is present. If the interview runs in the embed, forward the browser's `koji:interview_completed` event to your backend as a fast path. See [Webhook Setup](/docs/webhook-setup).\n\n**Can I use Koji with no dashboard at all?** Mostly. The MCP connector covers creating and configuring studies, editing briefs, publishing, importing respondents, generating reports and exporting data, and the REST API runs the interviews themselves. Some setup, such as creating API keys and panel recruitment, happens in the dashboard.\n\n## Related Resources\n\n- [Headless API Overview](/docs/headless-api-overview): full REST specification and code samples\n- [Starting Interviews via API](/docs/starting-interviews-via-api): step-by-step `POST /interviews/start` walkthrough\n- [Completing Interviews via API](/docs/completing-interviews-via-api): finalization, analysis triggers, and result retrieval\n- [Embed Widget Reference](/docs/embed-widget-reference): embed configuration\n- [Research Automation](/docs/research-automation-webhooks): building near-real-time research pipelines\n- [Webhook Setup](/docs/webhook-setup): why there are no outbound webhooks yet, and the patterns that replace them\n- [API Authentication](/docs/api-authentication): Bearer token issuance and rotation\n- [Structured Questions Guide](/docs/structured-questions-guide): the 6 question types returned in API responses\n- [MCP Integration Overview](/docs/mcp-overview): study management exposed to AI agents\n\n## Further reading on the blog\n\n- [B2B Customer Research: The Complete Guide for Product Teams (2026)](/blog/b2b-customer-research-guide-2026) — B2B customer research is harder than B2C — you are navigating buying groups of 10+ stakeholders, gatekeepers, and enterprise procurement cyc\n- [Customer Research Done Right: A Complete Guide for Product Teams](/blog/customer-research-done-right-a-complete-guide-for-product-teams) — Customer research is the foundation of every successful product decision. Learn the types, methods, and best practices that help product tea\n- [Customer Research for Product-Led Growth: The Complete Guide (2026)](/blog/customer-research-for-product-led-growth-2026) — Product analytics tells you what users do. It cannot tell you why they activate, churn, or expand. This guide covers the research questions,\n\n<!-- further-reading:blog -->\n","category":"API Reference","lastModified":"2026-10-18T04:21:07.325259+00:00","metaTitle":"User Research API: Embed AI Interviews into Any Product (Koji)","metaDescription":"A complete guide to Koji's User Research API. Run AI-moderated voice and text interviews from your backend, embed widgets in-product, and pull transcripts by polling the read endpoint.","keywords":["user research api","research api","headless user research","embed ai interview","programmatic user interviews","research webhooks api","user interview api","koji api"],"aiSummary":"The Koji User Research API exposes four REST endpoints (start, message, complete and read) plus an embed that posts browser events, letting developers run AI-moderated text and voice interviews from any backend. It is included on the Interviews and Enterprise plans, along with API keys and the MCP connector. Each API key belongs to one study and carries its own permissions. The start endpoint takes an optional respondent object (external_id, display_name, metadata), a mode and a locale, and returns an interview ID and session token. The API supports adaptive follow-up probing, 6 structured question types and an automatic 1 to 5 quality score per interview. Usage is billed in credits at 1 euro each (1 for text, 3 for voice, 5 for a report refresh), and interviews that fail the quality check are not charged. Koji has no outbound webhooks yet, so completion is detected by polling the read endpoint or forwarding the embed's completion event. The MCP connector exposes study management to AI agents such as Claude. Common patterns include in-product cancel-flow interviews, PLG onboarding research and research run by an AI agent.","aiPrerequisites":["Basic familiarity with REST APIs and Bearer authentication","A Koji workspace on the Interviews or Enterprise plan, and an API key for your study"],"aiLearningOutcomes":["Understand the four core REST endpoints for running AI interviews programmatically","Stream transcripts into your data pipeline by polling the read endpoint","Compare conversational research APIs against legacy survey APIs","Decide when to use the embed widget vs the raw REST API","Set up authentication, rate limits, and CORS correctly"],"aiDifficulty":"intermediate","aiEstimatedTime":"11 min read"}],"pagination":{"total":1,"returned":1,"offset":0}}