# Talkform

> Talkform gives AI agents a human handoff: an agent registers a workspace, asks a person to answer a focused form, and receives reviewed structured JSON. Text is the dependable default; optional voice is available only in a verified human workspace. It ships as a React widget, an HTTP API, a CLI, and an MCP server.

## Docs

- [Getting started](https://www.talkform.ai/docs/getting-started): register an agent workspace, send a respondent link, and retrieve reviewed JSON
- [Configuration](https://www.talkform.ai/docs/configuration): the AudioformConfig schema, fields, prompts, and validation
- [React widget](https://www.talkform.ai/docs/react): embed Talkform in any React product
- [HTTP API](https://www.talkform.ai/docs/http-api): create hosted respondent handoffs and retrieve reviewed results over HTTP
- [Python example](https://www.talkform.ai/docs/python-example): register an agent, create a hosted handoff, send its respondent URL, and poll the reviewed JSON result
- [Python webhook receiver](https://www.talkform.ai/docs/python-webhook-receiver): verify signed completion events and fetch reviewed JSON
- [CLI](https://www.talkform.ai/docs/cli): generate configs and export results from the terminal
- [MCP server](https://www.talkform.ai/docs/mcp): register an agent, use local schemas and templates, or call authenticated hosted handoff tools
- [Agents](https://www.talkform.ai/docs/agents): how AI agents should integrate with Talkform
- [Agent-readiness evidence](https://www.talkform.ai/evidence/agent-readiness): dated route denominator, method, and limitations

## Agent onboarding

- [agents.md](https://www.talkform.ai/agents.md): browser-agent onboarding, safe actions, and DOM hints
- [Agent discovery profile](https://www.talkform.ai/.well-known/agent-card.json): informational capabilities profile; no A2A endpoint is currently offered
- [AI agent manifest](https://www.talkform.ai/.well-known/ai-agent.json): guardrails, allowed/disallowed actions, rate expectations

## Schemas

- [AudioformConfig](https://www.talkform.ai/schemas/audioform-config.json): JSON schema for interview configs
- [AudioformSessionResult](https://www.talkform.ai/schemas/audioform-session-result.json): JSON schema for session exports

## Product

- [Live demo](https://www.talkform.ai/app): try a guided voice or text interview in the browser; demo data stays browser-local until export
- [Import a form](https://www.talkform.ai/import): turn a public Typeform, Google Forms, Jotform, or HubSpot form into an editable Talkform draft
- [FAQ](https://www.talkform.ai/faq): plain answers on imports, voice and text input, data handling, and limitations
- [Use cases](https://www.talkform.ai/use-cases): example deployments
- [Pricing](https://www.talkform.ai/pricing): free core text handoffs, 10/day machine workspaces, 100/day human-owned projects, 7-day links/results, and capped optional voice
- [Dashboard](https://www.talkform.ai/dashboard): claim and manage a human-owned project
- [Hosted handoff API](https://www.talkform.ai/docs/http-api): create project-scoped respondent links with POST /api/v1/handoffs, poll reviewed results, and delete handoffs

## Examples

- [AI skill tutor](https://www.talkform.ai/examples/ai-skill-tutor): a complete example interview config

## Optional

- [Blog](https://www.talkform.ai/blog): product notes and guides
- [RSS feed](https://www.talkform.ai/feed.xml)
- [Changelog](https://www.talkform.ai/changelog)
- [Contact](https://www.talkform.ai/contact): support@talkform.ai

## Agent registration and hosted handoff contract

- Register without an email or Clerk account with POST /api/v1/agents/register or talkform.register_agent using an optional name, optional production/test environment, and a fresh UUIDv4 idempotencyKey.
- The 201 response returns registration, project, key, a one-time secret, limits, and URLs. Machine workspaces start at 10 handoffs per day and voiceEligible true; save the secret immediately.
- Authenticate machine requests with Authorization: Bearer project-key from registration or /dashboard.
- Create with talkform.create_handoff or POST /api/v1/handoffs using config and idempotencyKey. Set branding.fromName, branding.purpose, and theme hex colors so the respondent page is product-owned. promptTitle is the human question.
- The create response includes respondentUrl, shareText, mode, and voiceEligible. Send shareText to the user who will share the link.
- Read status with talkform.get_handoff; retrieve reviewed structured values with talkform.get_result.
- Poll results every 10 seconds or slower. Pending returns HTTP 409; expired returns HTTP 410.
- Respondent links and completed-result access last 7 days. Configure signed handoff.completed webhooks with PUT /api/v1/webhook, or poll when no webhook is configured.
- Hosted results contain reviewed structured values and response mode; Talkform does not retain a transcript or generated summary.