> ## 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.

# Developer examples

> Run TypeScript examples for conducting qualitative research, retrieving study results, and searching existing evidence.

## Start with a runnable example

The [public userintuition-examples repository](https://github.com/Pen-and-Paper-AI/userintuition-examples) demonstrates three workflows using TypeScript. Your application controls the customer experience and interpretation; User Intuition provides research execution and evidence access.

```bash theme={null}
git clone https://github.com/Pen-and-Paper-AI/userintuition-examples.git
cd userintuition-examples
npm run demo
```

Requires Node.js 22.18 or later. Default fixture mode makes no network calls and requires no API key or spending. Every fixture is fictional; it demonstrates data handling, not measured research performance.

<Note>
  The results and search examples target the B2/C1 release. Exact endpoint and nested response compatibility is tracked in the repository's release checklist. Confirm the adapter against the released OpenAPI before using it in production.
</Note>

## Conduct a study

The example separates draft creation, Customize Plan turns, saved-plan review, a recruitment estimate, paid launch, monitoring, and report generation. A plan may require several conversational turns; relay questions rather than inventing answers. Save the study ID to resume.

The user chooses panel recruitment or their own participants. Before paid recruitment, review the current saved plan and full estimate. The example requires explicit live mode and a separate launch approval flag. That flag is not a backend budget limit or an idempotency guarantee.

[Open the study example](https://github.com/Pen-and-Paper-AI/userintuition-examples/tree/main/examples/conduct-a-study)

## Retrieve study results

Study results expose Study Findings, Participant Responses, Participant Profiles, and Recommended Next Steps. Findings and response summaries are analysis; exact quotations are source evidence; profiles describe the sample; recommendations propose further work.

Keep source references, interview IDs, coverage, and freshness with the report. An interview-level link does not necessarily identify the exact passage behind an answer. The example demonstrates answer-to-reference relationships and checks fictional quotations against their source messages. Retrieval does not regenerate analysis.

[Open the results example](https://github.com/Pen-and-Paper-AI/userintuition-examples/tree/main/examples/retrieve-study-results)

## Search existing research

Search locates relevant findings and participant-response summaries across authorized research. Keyword and semantic matching support exact names and related meanings. Inspect the returned study context, references, and search coverage, then retrieve the source report or interview.

Recommendations are distinct from observed evidence. A search over summaries does not prove that all transcript passages were searched. Empty results are different from an API failure, and repeated matches from one interview are not independent participants. Your agent performs the final synthesis.

[Open the search example](https://github.com/Pen-and-Paper-AI/userintuition-examples/tree/main/examples/search-research)

## Connect through MCP or CLI

Use the [MCP setup guide](/mcp-server/overview) for authentication and current tool discovery. The examples repository includes a [matching MCP and CLI walkthrough](https://github.com/Pen-and-Paper-AI/userintuition-examples/blob/main/docs/mcp-cli.md). REST and tool schemas may differ; use the contract for the surface you call.

## Verify before production use

Run fixture tests and the release-schema check, then validate the narrow live workflow your integration needs with an authorized test study. Do not publish real participant data in a reproduction. A timed-out write can leave an uncertain outcome; inspect persisted state before retrying.

The [release checklist](https://github.com/Pen-and-Paper-AI/userintuition-examples/blob/main/docs/release-check.md) covers response shapes, citations, pagination, coverage, errors, and source access. The [API request examples](/api-reference/request-examples) remain the detailed reference for released operations.