# Telltale documentation

> Agent detection for signed-in browser sessions: a held browser SDK, server verification with categorical verdicts, and reviewed agent tools. Unknown is never human.

## For owners

- [How Telltale works](https://app.trytelltale.dev/docs/how-it-works.md): What 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 report](https://app.trytelltale.dev/docs/diagnostic-report.md): The 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.
- [Pricing](https://app.trytelltale.dev/docs/pricing.md): Free, Starter, Growth and Enterprise: per identified user a month, soft limits, and safety controls on every plan.
- [Trust kit: privacy and security](https://app.trytelltale.dev/docs/trust.md): Data 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

- [Quickstart](https://app.trytelltale.dev/docs/quickstart.md): Install 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 demo](https://app.trytelltale.dev/docs/demo.md): The 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 agent](https://app.trytelltale.dev/docs/coding-agent.md): Install prompt, open-in-your-IDE links and the key-free docs MCP server for Claude Code, Cursor and VS Code.
- [Setup skill for coding agents](https://app.trytelltale.dev/docs/setup-skill.md): Written 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 Cloudflare](https://app.trytelltale.dev/docs/cloudflare.md): Managed Zaraz installation on exact hostnames, identity events, activity confirmation and removal.
- [Deployment options](https://app.trytelltale.dev/docs/deployment.md): Hosted 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.js](https://app.trytelltale.dev/docs/nextjs.md): App 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)](https://app.trytelltale.dev/docs/react.md): 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 WordPress](https://app.trytelltale.dev/docs/wordpress.md): WPCode Header & Footer or a child theme, consent, the logged-in user ID, caching plugin exclusions and checking it worked.
- [Install on Shopify](https://app.trytelltale.dev/docs/shopify.md): theme.liquid before </head>, consent, the signed-in customer ID, why not custom pixels, and why checkout is not observed.
- [Install on Webflow](https://app.trytelltale.dev/docs/webflow.md): Site settings › Custom code › Head code, then Publish; consent, membership-tool identify and checking it on the published site.
- [Google Tag Manager](https://app.trytelltale.dev/docs/gtm.md): Site-specific template or a Custom HTML tag, consent settings, CMP control or ordinary start, identity data-layer events, CSP and Preview.
- [It's not working](https://app.trytelltale.dev/docs/troubleshooting.md): By 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 SDK](https://app.trytelltale.dev/docs/sdk.md): Recording on page load or a held start, consent, identity, protected actions, native POST forms, getClient() and the hosted loader.
- [Verdicts and authorization](https://app.trytelltale.dev/docs/verdicts.md): What 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 accuracy](https://app.trytelltale.dev/docs/accuracy.md): The 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 2026](https://app.trytelltale.dev/docs/accuracy-report-2026-11.md): Opens 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 verdicts](https://app.trytelltale.dev/docs/accuracy-assistive-protocol.md): What 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 recovery](https://app.trytelltale.dev/docs/server.md): Verify, identify, usage metering, stable errors and the public OpenAPI contract.
- [Step-up for held actions](https://app.trytelltale.dev/docs/step-up.md): Let 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 Fingerprint](https://app.trytelltale.dev/docs/edge-evidence.md): Forward 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 retries](https://app.trytelltale.dev/docs/errors.md): Every /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 HTTP](https://app.trytelltale.dev/docs/server-adapters.md): Download the versioned adapter files with SHA-256 integrity, or call the server API with curl or fetch.
- [Webhooks](https://app.trytelltale.dev/docs/webhooks.md): Standard Webhooks signing, verification, retries, secret rotation, and moving off the old Observatory-Signature header from before Standard Webhooks.
- [Export to a spreadsheet or BI](https://app.trytelltale.dev/docs/export.md): Every Download in the dashboard and every read API, what each file holds, and how to keep agent names with how we know them.
- [S3 export](https://app.trytelltale.dev/docs/s3-export.md): A 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 comparisons](https://app.trytelltale.dev/docs/workflow-comparisons.md): Report paired UI and tool trials with matched tasks, observed completion, duration and retries; show only supported time differences.
- [Usage metering](https://app.trytelltale.dev/docs/usage-metering.md): Report completed work, deduplicate events and reconcile agent usage by account and category.
- [Agent monetization](https://app.trytelltale.dev/docs/agent-monetization.md): Detect signed or weak-marker agents, offer an API or agent seat in the page, and meter the work with the usage API.
- [Agent-usage ledger](https://app.trytelltale.dev/docs/usage-ledger.md): Chargeable (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 playbook](https://app.trytelltale.dev/docs/agent-seat-playbook.md): A 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 agents](https://app.trytelltale.dev/docs/approved-route.md): Tell 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 servers](https://app.trytelltale.dev/docs/mcp.md): One 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 mode](https://app.trytelltale.dev/docs/custom-events.md): Tag 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 APIs](https://app.trytelltale.dev/docs/api-channel.md): One 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 data](https://app.trytelltale.dev/docs/analytics-mcp.md): A 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 summaries](https://app.trytelltale.dev/docs/ai-summaries.md): Opt-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 do](https://app.trytelltale.dev/docs/understand.md): One 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 fields](https://app.trytelltale.dev/docs/deep-insights.md): Opt 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 needed](https://app.trytelltale.dev/docs/agent-feedback.md): Opt 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 WebMCP](https://app.trytelltale.dev/docs/webmcp.md): Reviewed agent tools, native WebMCP browser and agent compatibility today, and the in-page runner fallback.
- [Authentication and keys](https://app.trytelltale.dev/docs/authentication.md): Publishable and server keys, rotation with overlap, and the Better Auth identity adapter.
- [Content Security Policy](https://app.trytelltale.dev/docs/csp.md): Nonce with strict-dynamic or an exact host allowlist; never unsafe-inline or unsafe-eval.

## Consent and frameworks

- [Consent bridge and identity reconnection](https://app.trytelltale.dev/docs/consent.md): A page-owned bridge that keeps the latest CMP decision while the SDK loads, and current-identity reconnection.
- [Vue and Nuxt placement](https://app.trytelltale.dev/docs/nuxt.md): Vue SPA and Nuxt client-only plugin placement with identity reconnection on consent changes.
- [OneTrust consent recipe](https://app.trytelltale.dev/docs/consent-onetrust.md): Held start, a configurable OneTrust group, and withdrawal when a decision stops being valid.
- [Cookiebot consent recipe](https://app.trytelltale.dev/docs/consent-cookiebot.md): Held start, a configurable Cookiebot category, and withdrawal including site withdraw buttons.
- [Sourcepoint consent recipe](https://app.trytelltale.dev/docs/consent-sourcepoint.md): Held start, then grant or withdraw from Sourcepoint consent events or custom choice actions.

## Trust

- [Data location and retention](https://app.trytelltale.dev/docs/data-retention.md): Where data lives and how long each kind is kept by default.
- [SOC 2 plan](https://app.trytelltale.dev/docs/soc2.md): Controls in place, the gaps, and the timeline to a SOC 2 Type I and Type II report.
- [Redaction controls](https://app.trytelltale.dev/docs/redaction.md): What 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 impact](https://app.trytelltale.dev/docs/sdk-performance.md): The SDK's compressed size and main-thread cost, measured, with the method.

## API reference

- [Look up a session later: verdict, evidence, identity and decisions](https://app.trytelltale.dev/docs/api-get-session.md): GET /api/v1/sessions/{sessionId}: For a backend that stored the session ID with its own record (an exam attempt, an order) and checks it afterwards.
- [Verify evidence before a protected action](https://app.trytelltale.dev/docs/api-verify-protected-action.md): POST /api/v1/verify: Apply your own authenticated account authorization and the returned decision.
- [Associate server-verified identity](https://app.trytelltale.dev/docs/api-identify-session.md): POST /api/v1/identify: Derive IDs from your authenticated session and account membership.
- [Report completed chargeable units](https://app.trytelltale.dev/docs/api-record-completed-usage.md): POST /api/v1/usage: Requires server-verified identity.
- [Record custom events from your server (shape-only: a name, a time, IDs and tags)](https://app.trytelltale.dev/docs/api-record-custom-events.md): POST /api/v1/events: Counted per day, per account and month; never a message, parameters or payload: unknown fields are refused.
- [Record tool calls through your MCP server (Telltale for MCP servers)](https://app.trytelltale.dev/docs/api-record-mcp-calls.md): POST /api/v1/mcp/calls: Shapes only: unknown fields are refused, never dropped, so no argument, result, error text or header can be stored.
- [Check your rule (Control › Rules) for a protected MCP tool before it runs](https://app.trytelltale.dev/docs/api-decide-mcp-call.md): POST /api/v1/mcp/decide: The AI agent branch of the tool's saved rule decides (every MCP caller is an agent's client); with no saved rule the defaults apply (AI agent: hold for review).
- [Record calls to your own API (Telltale for APIs)](https://app.trytelltale.dev/docs/api-record-api-calls.md): POST /api/v1/api-calls: Shapes only: unknown fields are refused, never dropped, so no body, query value, header or credential can be stored.
- [Whether the workspace keeps the why field (opt in)](https://app.trytelltale.dev/docs/api-get-mcp-why-field.md): GET /api/v1/mcp/why: The Telltale MCP SDK reads this at start and every five minutes, and adds the optional reason parameter to the tools named in its why option only while enabled is true.
- [Whether the workspace keeps agent feedback (opt in)](https://app.trytelltale.dev/docs/api-get-agent-feedback.md): GET /api/v1/agent-feedback/state: The Telltale MCP SDK reads this at start and lists its feedback tool only while enabled is true.
- [Record what an AI agent said it needed and could not find (agent feedback)](https://app.trytelltale.dev/docs/api-record-agent-feedback.md): POST /api/v1/agent-feedback: Stored only while the workspace has agent feedback on; otherwise answered {stored: false, reason: "off"} and nothing is kept.
- [Whether the Site stores Deep insights captures (opt in)](https://app.trytelltale.dev/docs/api-get-deep-insights.md): GET /api/v1/deep-insights: The Telltale MCP and API SDKs read this at start and send captured fields only while enabled is true.
- [Check your rule (Control › Rules) for a protected API route before the handler runs](https://app.trytelltale.dev/docs/api-decide-api-call.md): POST /api/v1/api-calls/decide: The branch of the call's verdict decides: AI agent (any agent evidence) or Unknown; there is no Human branch on this channel.
- [The state of a held API call](https://app.trytelltale.dev/docs/api-get-api-decision.md): GET /api/v1/api-calls/decisions/{decisionId}: Poll this while a call is held (decision review).
- [Report your own step-up for a held API call](https://app.trytelltale.dev/docs/api-step-up-api-call.md): POST /api/v1/api-calls/decisions/{decisionId}/step-up: passed approves the held call for one use within 15 minutes (the next decide with approvedDecisionId); failed rejects it.
- [The state of a held MCP tool call](https://app.trytelltale.dev/docs/api-get-mcp-decision.md): GET /api/v1/mcp/decisions/{decisionId}: Poll this while a call is held (decision review).
- [Report your own step-up for a held MCP tool call](https://app.trytelltale.dev/docs/api-step-up-mcp-call.md): POST /api/v1/mcp/decisions/{decisionId}/step-up: passed approves the held call for one use within 15 minutes (the next decide with approvedDecisionId); failed rejects it.
- [Issue a scoped, short-lived agent token for one account](https://app.trytelltale.dev/docs/api-issue-agent-token.md): POST /api/v1/agent-tokens: 409 agent_tokens_disabled while agent tokens are off for the Site (Settings); 409 tool_not_approved or tool_not_read_only for a tool that is not reviewed and enabled, or that changes data (writes stay in the page).
- [Verify an agent token for one tool call](https://app.trytelltale.dev/docs/api-verify-agent-token.md): POST /api/v1/agent-tokens/verify: A refusal is 200 {valid:false, reason} in fixed words, never an error; nothing is recorded for it.
- [Revoke one agent token, or every live token of an account](https://app.trytelltale.dev/docs/api-revoke-agent-tokens.md): POST /api/v1/agent-tokens/revoke: Send exactly one of token (the token itself), tokenId (from the issue response) or accountId (every live token of that account).
- [Record one controlled UI or tool task attempt](https://app.trytelltale.dev/docs/api-record-workflow-trial.md): POST /api/v1/workflow-trials: Requires a live session with server-associated identity.
- [Export the Site’s discovered customer API](https://app.trytelltale.dev/docs/api-get-discovered-open-api.md): GET /api/v1/discovery/openapi.json
- [Read the agent-usage ledger](https://app.trytelltale.dev/docs/api-get-usage-ledger.md): GET /api/v1/usage/ledger: Completed-work units (POST /api/v1/usage) counted as chargeable agent (high confidence: verified identity, an automation trace, injected input, sustained behaviour, a behaviour change or two or more behaviour families agreeing), behaviour-only agent (medium confidence, never charged), human or unknown, per Site, account, user and UTC day.
- [Report metered agent usage per account and category](https://app.trytelltale.dev/docs/api-get-agent-usage.md): GET /api/v1/agent-usage.json: Retained tool executions and agent session-minutes for the requested period (default seven days, at most the Site usage retention).
- [Human, agent and unknown interaction minutes and sessions per day](https://app.trytelltale.dev/docs/api-get-activity.md): GET /api/v1/activity.json: For BI tools: interaction minutes per class (human, agent, unknown, mixed) and daily session totals by last-observed verdict, in UTC-day or ISO-week buckets that partition [since, until).
- [Read a decision and its review state](https://app.trytelltale.dev/docs/api-get-decision.md): GET /api/v1/decisions/{decisionId}: approvalToken is returned only while an approved hold can still be redeemed.
- [Report what your backend did (informational)](https://app.trytelltale.dev/docs/api-report-decision-outcome.md): POST /api/v1/decisions/{decisionId}/outcome: Informational only: it never changes the decision.
- [Send a decision to the hosted review queue](https://app.trytelltale.dev/docs/api-request-decision-review.md): POST /api/v1/decisions/{decisionId}/review: Use when your own policy holds an action that Telltale allowed.
- [Report the result of your own step-up check for a held decision](https://app.trytelltale.dev/docs/api-report-step-up.md): POST /api/v1/decisions/{decisionId}/step-up: For a decision held for review (review), your backend may run its own check (passkey or MFA re-auth, Turnstile, its own approval) instead of waiting for the hosted queue.
- [Redeem a one-time approval token](https://app.trytelltale.dev/docs/api-redeem-approval.md): POST /api/v1/approvals/redeem: Bound to the same session, action and target; valid once, for 15 minutes after approval.
- [Integration health for this Site](https://app.trytelltale.dev/docs/api-get-integration-status.md): GET /api/v1/integration-status: Server key last use, verify outcomes by code over seven days (allow, review and deny from the decision history; failure codes such as unauthorized, session_reinit_required or rate_limited), webhook delivery status with a fixed reason category, live browser sessions, database health and warnings such as policy_missing.
- [List decisions for this Site, newest first, one page at a time](https://app.trytelltale.dev/docs/api-list-decisions.md): GET /api/v1/decisions.json: Ordered by created time, newest first (ties by decision ID).
- [Export saved workflow definitions](https://app.trytelltale.dev/docs/api-get-workflow-definitions.md): GET /api/v1/discovery/workflows.json

## Compatibility API (/v1)

- [Compatibility API (/v1) verification](https://app.trytelltale.dev/docs/api-compat-verify.md): POST /v1/verify: Uses the stricter actionVerdict from /api/v1/verify (analytics-only AI agent is excluded), returned in the v1 shape {verdict, score}.
- [Compatibility API (/v1) server identity](https://app.trytelltale.dev/docs/api-compat-identify.md): POST /v1/identify: Associates server-verified userId and/or accountId (each at most 512 characters).
- [Compatibility API (/v1) discovered API export](https://app.trytelltale.dev/docs/api-compat-discovered-open-api.md): GET /v1/discovery/openapi.json: The reviewed actions of /api/v1/discovery/openapi.json in the v1 DiscoveredOpenApiDocument shape: exactly openapi 3.1.1, info {title: Discovered API, version: 1} and paths, with ETag/If-None-Match.
- [Compatibility API (/v1) session lookup](https://app.trytelltale.dev/docs/api-compat-get-session.md): GET /v1/sessions/{sessionId}: The v1 SessionResponse, exactly: {sessionId, status, identity, verdict}: status active or ended (consent withdrawn reads ended), verdict the action verdict (unknown after withdrawal), no score.

## Machine-readable

- Full corpus: https://app.trytelltale.dev/llms-full.txt
- Server API contract (OpenAPI 3.1): https://app.trytelltale.dev/openapi.json
- API catalog (RFC 9727): https://app.trytelltale.dev/.well-known/api-catalog
- API explorer: https://app.trytelltale.dev/docs/api-explorer
- Docs MCP server (Streamable HTTP, no key): https://app.trytelltale.dev/mcp
- MCP server card: https://app.trytelltale.dev/.well-known/mcp/server-card.json