Telltale documentation
Telltale shows which customer accounts AI agents use across your app, your API and your MCP server, and lets you hold risky actions and charge for agent work. These pages are public and need no key.
Start here
- WebsiteAdd the tag or the SDK to your signed-in app. Each session reads Human, AI agent or Unknown, per account.
- MCP serverWrap your MCP server once: every agent tool call per account, with no content sent.
- APIOne middleware for your own API: every agent call per account and route.
- Verify before a risky actionCheck the verdict on your server, then allow, hold for review or deny under your own rule.
Not a developer? See your agent report. Prefer to watch it first? Open the live demo. Using Claude Code, Cursor or VS Code? Set up with a coding agent. Every field of a request: the API reference.
For owners
What Telltale does, your report, plans and privacy. No code.
- How Telltale worksWhat Telltale does in plain words: it watches how a signed-in page is used and tells you whether a person or an AI agent did it, then how the verdict reaches your own authorization decision.
- Your agent reportThe free, change-nothing report: accounts with AI agent activity, agent sessions across your website, MCP server and API, named agents with how we know, the Unknown share, what is chargeable, and your team as known humans.
- PricingFree, Starter, Growth and Enterprise: per identified user a month, soft limits, and safety controls on every plan.
- Trust kit: privacy and securityData location and retention, redaction, the SOC 2 plan and the script's page impact; the DPA, privacy policy, security overview and subprocessor list on request.
Getting started
- QuickstartInstall the SDK (it records on page load; hold it if you show a consent banner), send a session token to your backend and verify one protected action.
- Live demoThe no-install demo at /try: eight fictional tasks, the agent prompt, the session panel states and the visitor-only verdict endpoint.
- Set up with a coding agentInstall prompt, open-in-your-IDE links and the key-free docs MCP server for Claude Code, Cursor and VS Code.
- Setup skill for coding agentsWritten for a coding agent asked to set up Telltale: which install fits the app, the consent question, identify from the server, MCP and API, checking it works and what never to do.
- Install with CloudflareManaged Zaraz installation on exact hostnames, identity events, activity confirmation and removal.
- Deployment optionsHosted Telltale, local mode on loopback, one server with password sign-in, and production on Postgres with Supabase Auth or Docker; what is never public.
Install
- Install on Next.jsApp Router and Pages Router with next/script, consent, identify from a client component, CSP, the consent bridge and connectIdentity.
- Install on React (Vite or Create React App)The tag in index.html or a once-only loader hook, consent, identify and reset from your auth, CSP and checking it worked.
- Install on WordPressWPCode Header & Footer or a child theme, consent, the logged-in user ID, caching plugin exclusions and checking it worked.
- Install on Shopifytheme.liquid before </head>, consent, the signed-in customer ID, why not custom pixels, and why checkout is not observed.
- Install on WebflowSite settings › Custom code › Head code, then Publish; consent, membership-tool identify and checking it on the published site.
- Google Tag ManagerSite-specific template or a Custom HTML tag, consent settings, CMP control or ordinary start, identity data-layer events, CSP and Preview.
- It's not workingBy symptom: nothing arrives, the address is not allowed, a wrong key, waiting for consent, a CSP block, no signed-in user linked, and what the install check can see.
Guides
- Browser SDKRecording on page load or a held start, consent, identity, protected actions, native POST forms, getClient() and the hosted loader.
- Verdicts and authorizationWhat human, agent and unknown mean and do not mean, attribution strengths, why a verdict never authorizes an action, and stale and unknown handling.
- How we measure accuracyThe headline result, how sessions are labelled (controlled, reviewer, self-declared), what is set aside for testing, and what the numbers do and do not cover.
- Accuracy report, November 2026Opens the public report page: how many AI agent sessions were caught and how many people were wrongly flagged, measured on a published research study of seven commercial AI agents, and what to keep in mind.
- Assistive technology and verdictsWhat screen reader, voice control, switch access and keyboard-only users read as (Human or Unknown, never AI agent on their own input), and how a medium-confidence hold treats them.
- Server API and recoveryVerify, identify, usage metering, stable errors and the public OpenAPI contract.
- Step-up for held actionsLet a held person through with your own check (a passkey, a two-step code, Turnstile): the onHold handler for the server adapter, MCP and API, with Express and Next.js examples.
- Edge evidence: Cloudflare and FingerprintForward Cloudflare Bot Management and Fingerprint Smart Signals with verify as labelled sources, how strong each is, and the Cloudflare Worker that forwards and enforces.
- Errors and retriesEvery /api/v1 and /v1 error code with its status, meaning and fix, which ones the adapter retries, and session_reinit_required recovery.
- Server adapters and raw HTTPDownload the versioned adapter files with SHA-256 integrity, or call the server API with curl or fetch.
- WebhooksStandard Webhooks signing, verification, retries, secret rotation, and moving off the old Observatory-Signature header from before Standard Webhooks.
- Export to a spreadsheet or BIEvery Download in the dashboard and every read API, what each file holds, and how to keep agent names with how we know them.
- S3 exportA daily gzipped NDJSON file of agent categories in your own S3 bucket: the IAM role with an external ID, the columns, the schedule and retries.
- Measured workflow comparisonsReport paired UI and tool trials with matched tasks, observed completion, duration and retries; show only supported time differences.
- Usage meteringReport completed work, deduplicate events and reconcile agent usage by account and category.
- Agent monetizationDetect signed or weak-marker agents, offer an API or agent seat in the page, and meter the work with the usage API.
- Agent-usage ledgerChargeable (high-confidence AI agent), behaviour-only, human and unknown units per account and day with the evidence for each, corrections, Stripe meters and account alerts.
- Agent seat playbookA template terms clause, in-app notice wording, an agent seat offer and how to use the ledger when you talk to the customer.
- Approved route for agentsTell agents your reviewed tools exist, count calls through them per account whatever the verdict, and issue scoped agent tokens for your API.
- Telltale for MCP serversOne wrapper around your MCP server: every agent tool call per account and channel, no content sent, the opt-in why field, rules for protected tools and stateless servers.
- Custom events, tags and debug modeTag MCP and API calls with categories, count named events per account, see tool and route performance, get notices when a tool fails, and turn on local-only debug lines. Shape-only: no messages or payloads.
- Telltale for APIsOne middleware for Node http, Express, Next.js, Hono or Fastify: every agent call to your own API per account and route, shapes only, how we know it was an agent, and rules for protected routes.
- Ask your own agent about your dataA read-only MCP server for Claude, Claude Code, Cursor, VS Code or Codex: sign in from Claude or use an analytics key, one site each, counts and categories only, never content.
- AI summariesOpt-in goal names, grouped stuck problems and possible-hallucination flags, chosen from your own tool list by TypeSafe Jev or Claude Haiku. What is sent, budgets and how to turn it off.
- Understand what agents are trying to doOne switch, off by default: the MCP why field and AI goals with their success rate, labelled AI summary. What is stored, for how long, and what turning it off deletes.
- Deep insights: stored tool-call fieldsOpt in, owner-enabled: keep the MCP and API fields you list for 7 to 30 days, redacted in your SDK first, never headers or credentials, shown as Captured fields in the session drawer.
- Agent feedback: what agents neededOpt in per workspace: an MCP tool where agents say what they needed and could not find. Redacted twice, 500 characters, 30 days; shown in Issues, the session and the bell, never in verdicts, rules, billing or AI summaries.
- Agent tools and WebMCPReviewed agent tools, native WebMCP browser and agent compatibility today, and the in-page runner fallback.
- Authentication and keysPublishable and server keys, rotation with overlap, and the Better Auth identity adapter.
- Content Security PolicyNonce with strict-dynamic or an exact host allowlist; never unsafe-inline or unsafe-eval.
Consent and frameworks
- Consent bridge and identity reconnectionA page-owned bridge that keeps the latest CMP decision while the SDK loads, and current-identity reconnection.
- Vue and Nuxt placementVue SPA and Nuxt client-only plugin placement with identity reconnection on consent changes.
- OneTrust consent recipeHeld start, a configurable OneTrust group, and withdrawal when a decision stops being valid.
- Cookiebot consent recipeHeld start, a configurable Cookiebot category, and withdrawal including site withdraw buttons.
- Sourcepoint consent recipeHeld start, then grant or withdraw from Sourcepoint consent events or custom choice actions.
Trust
- Data location and retentionWhere data lives and how long each kind is kept by default.
- SOC 2 planControls in place, the gaps, and the timeline to a SOC 2 Type I and Type II report.
- Redaction controlsWhat is never collected (typed content, credentials, cookies, request values), sensitive routes, data-telltale-ignore, capture levels, consent and what forwarding carries.
- Script size and page impactThe SDK's compressed size and main-thread cost, measured, with the method.
API reference
For developers: /api/v1, the full server API your backend calls with a server key. Use it for new integrations.
- Look up a session later: verdict, evidence, identity and decisions
GET/api/v1/sessions/{sessionId} - Verify evidence before a protected action
POST/api/v1/verify - Associate server-verified identity
POST/api/v1/identify - Report completed chargeable units
POST/api/v1/usage - Record custom events from your server (shape-only: a name, a time, IDs and tags)
POST/api/v1/events - Record tool calls through your MCP server (Telltale for MCP servers)
POST/api/v1/mcp/calls - Check your rule (Control › Rules) for a protected MCP tool before it runs
POST/api/v1/mcp/decide - Record calls to your own API (Telltale for APIs)
POST/api/v1/api-calls - Whether the workspace keeps the why field (opt in)
GET/api/v1/mcp/why - Whether the workspace keeps agent feedback (opt in)
GET/api/v1/agent-feedback/state - Record what an AI agent said it needed and could not find (agent feedback)
POST/api/v1/agent-feedback - Whether the Site stores Deep insights captures (opt in)
GET/api/v1/deep-insights - Check your rule (Control › Rules) for a protected API route before the handler runs
POST/api/v1/api-calls/decide - The state of a held API call
GET/api/v1/api-calls/decisions/{decisionId} - Report your own step-up for a held API call
POST/api/v1/api-calls/decisions/{decisionId}/step-up - The state of a held MCP tool call
GET/api/v1/mcp/decisions/{decisionId} - Report your own step-up for a held MCP tool call
POST/api/v1/mcp/decisions/{decisionId}/step-up - Issue a scoped, short-lived agent token for one account
POST/api/v1/agent-tokens - Verify an agent token for one tool call
POST/api/v1/agent-tokens/verify - Revoke one agent token, or every live token of an account
POST/api/v1/agent-tokens/revoke - Record one controlled UI or tool task attempt
POST/api/v1/workflow-trials - Export the Site’s discovered customer API
GET/api/v1/discovery/openapi.json - Read the agent-usage ledger
GET/api/v1/usage/ledger - Report metered agent usage per account and category
GET/api/v1/agent-usage.json - Human, agent and unknown interaction minutes and sessions per day
GET/api/v1/activity.json - Read a decision and its review state
GET/api/v1/decisions/{decisionId} - Report what your backend did (informational)
POST/api/v1/decisions/{decisionId}/outcome - Send a decision to the hosted review queue
POST/api/v1/decisions/{decisionId}/review - Report the result of your own step-up check for a held decision
POST/api/v1/decisions/{decisionId}/step-up - Redeem a one-time approval token
POST/api/v1/approvals/redeem - Integration health for this Site
GET/api/v1/integration-status - List decisions for this Site, newest first, one page at a time
GET/api/v1/decisions.json - Export saved workflow definitions
GET/api/v1/discovery/workflows.json
Compatibility API (/v1)
/v1, the v1 request and response shapes that existing agent-verification integrations were built on. Use it only for those; new integrations use /api/v1.
- Compatibility API (/v1) verification
POST/v1/verify - Compatibility API (/v1) server identity
POST/v1/identify - Compatibility API (/v1) discovered API export
GET/v1/discovery/openapi.json - Compatibility API (/v1) session lookup
GET/v1/sessions/{sessionId}