# UserTold.ai

> User feedback for AI agents: turn your agent's research questions into interviews with real users inside the product, then return source-linked evidence it can verify and act on.

> Many teams already have agents that can turn issues into merged PRs. UserTold.ai gives those agents the missing upstream connection to what real users said and did.

## Product Promise

UserTold conducts in-product interviews with real users and captures product usage, speech, clicks, navigation, and page context. Study scripts use `talk` for live interviews, `observe` for silent task observation, and scripted `speak` for instructions, transitions, and thanks. Planned debriefs turn observed behavior into focused follow-up questions. Completed sessions become source-linked evidence with quotes, page paths, actions, and confidence. Project-aware humans or agents verify that evidence before pushing work to Linear or GitHub.

## When to use UserTold.ai

Use UserTold when an agent or product team needs evidence from real product use before deciding what to build: finding where users get stuck, learning why users switch, testing onboarding or a workflow, turning repeated feedback into source-linked Findings, or checking whether a shipped fix recurs. Start with the in-product widget for research capture, MCP for agent-native workflows, the CLI for scripts and CI, or the REST API for direct integrations. Exact REST schemas are at https://usertold.ai/openapi.json.

## Documentation

- [Pricing](https://usertold.ai/pricing.md)
- [Customer evidence leaderboard](https://usertold.ai/leaderboard.md)
- [Quickstart](https://usertold.ai/docs/quickstart.md)
- [Glossary](https://usertold.ai/docs/glossary.md)
- [Core Concepts](https://usertold.ai/docs/concepts.md)
- [Widget Integration](https://usertold.ai/docs/widget.md)
- [Studies](https://usertold.ai/docs/studies.md)
- [Study Runtime](https://usertold.ai/docs/study-runtime.md)
- [API Reference](https://usertold.ai/docs/api.md)
- [MCP Integration](https://usertold.ai/docs/mcp.md)
- [Methodology](https://usertold.ai/docs/methodology.md)
- [CLI Reference](https://usertold.ai/docs/cli.md)
- [Study Design Guide](https://usertold.ai/guides/study-design.md)
- [Agentic User Research](https://usertold.ai/guides/agentic-user-research.md)
- [In-Product User Interviews: When They Fit](https://usertold.ai/guides/in-product-ai-interviews.md)
- [From User Interviews to Linear and GitHub Issues](https://usertold.ai/guides/interviews-to-issues.md)
- [Track Resolved Evidence](https://usertold.ai/guides/track-resolved-evidence.md)
- [Research Script Templates](https://usertold.ai/guides/research-script-templates.md)
- [Participant Consent](https://usertold.ai/guides/participant-consent.md)
- [Find Why Users Get Stuck Before They Leave](https://usertold.ai/guides/find-where-users-get-stuck.md)
- [Learn Why Users Switch](https://usertold.ai/guides/learn-why-users-switch.md)
- [Turn Feedback Into Work Worth Building](https://usertold.ai/guides/prioritize-fixes-with-evidence.md)
- [How to Identify User Needs](https://usertold.ai/guides/identify-user-needs.md)
- [How to Analyze User Interviews](https://usertold.ai/guides/analyze-user-interviews.md)
- [AI User Interviewer for In-Product Research](https://usertold.ai/features/ai-user-interviewer.md)
- [Pricing Page Research: Understand Plan Choice](https://usertold.ai/use-cases/pricing-page-research.md)
- [For Agents](https://usertold.ai/for-agents.md)
- [Agentic Loops](https://usertold.ai/agentic-loops.md)
- [How It Works](https://usertold.ai/how-it-works.md)
- [MCP Technical Verification](https://usertold.ai/mcp-review.md)
- [Changelog](https://usertold.ai/changelog.md)
- [About](https://usertold.ai/about.md)

## MCP Server

- Base URL: https://mcp.usertold.ai/mcp
- Protocol: HTTPS JSON-RPC over POST
- Auth: OAuth 2.1 + PKCE via your MCP client

## Quick Start

```sh
# Mint a user-delegated bearer token for write-capable CLI automation:
usertold auth login
export USERTOLD_API_KEY="$(usertold auth token --json | jq -r .token)"
usertold auth whoami --json
# Read profile.personal_org_handle from the response.
usertold init --org <your_personal_org_handle> --name "My Product" --format json --yes
usertold project use <orgHandle>/<projectHandle>
usertold study list --json
```

For protocol-native agent auth, read https://usertold.ai/auth.md. The anonymous flow mints a `usk_...` API key by posting `{"type":"anonymous","requested_credential_type":"api_key"}` to `/agent/auth`, then claiming it with `/agent/auth/claim` and `/agent/auth/claim/complete` after the email OTP arrives. That key is read-only; write-capable agent credentials require a trusted-provider ID-JAG with `agent:write`.

## Surface Discovery

The CLI is the canonical agentic surface. Add `--json` to help for a machine-readable list of the discoverable command surface:

```sh
usertold --help --json | jq '.commands[].name'
```