Telltale for APIs

Some agents skip your pages and your MCP server and call your API directly. Telltale for APIs records those calls, per account and per route, beside the agents in your pages and the agents using your MCP server: one record of AI agent activity across every account and every channel.

It's one middleware in the server you already run: Node's http server, Express, Next.js route handlers, Hono or Fastify. Your routes, handlers and responses stay as they are. Telltale never receives a request's content.

#What you get

• Per account and per route: calls, errors (by status class), refusals and how long each call took, for routes such as POST /v1/invoices/:id.
• Which agents, and how we know: each call that carries agent evidence is labelled with the agent and how we know (Verified by token, Verified, Published IP range or Declared). A call with no agent evidence is Unknown. This channel has no human signals, so a call is never labelled Human, and Unknown never means a person.
• One record per account: agent calls are approved-route calls with channel api, so they land in the agent-usage ledger, the account drawer, Accounts › All accounts, Home and Charge › Usage, split by channel (browser, MCP server, API).
• Issues: agent calls that failed (server errors, refused input, not allowed) are counted in Issues and in agent goals.
• Rules for protected routes: a route you name asks for your rule (Control › Rules) before your handler runs: allow, hold for review (with your own step-up) or deny.

#Install

Node 18+ or any runtime with fetch and Web Crypto. The middleware has no dependencies.

1. Download the adapter, check its SHA-256 against the adapters table, and put it beside your server code. It is an ES module: in a project whose package.json says "type": "commonjs" (what npm init writes), save the two files as telltale-api.mjs and telltale-api.d.mts and import ./telltale-api.mjs:

   Shell

   curl -sSo telltale-api.js https://app.trytelltale.dev/adapters/v1/api.js
   curl -sSo telltale-api.d.ts https://app.trytelltale.dev/adapters/v1/api.d.ts

2. Create the client once per process, with the Site's server key (Settings › Channels › Server keys). The key stays on your server:

   JavaScript

   import { createTelltaleApi } from './telltale-api.js';
   
   export const telltale = createTelltaleApi({
     endpoint: 'https://app.trytelltale.dev',
     serverKey: process.env.TELLTALE_SERVER_KEY,
     identify: (req) => ({ accountId: req.user?.accountId, userId: req.user?.id }),   // your own opaque IDs
   });
   
   process.on('SIGTERM', async () => { await telltale.close(); process.exit(0); });

3. Add it to your framework (below), then make one request to your API. Settings › Channels › API › Is it working? turns to "Working" with the time of the last batch, usually within five seconds.

#Node http

import http from 'node:http';
http.createServer(telltale.node((req, res) => { /* your handler */ })).listen(3000);

The Node server has no route templates of its own, so the built-in normaliser (below) or your route function names the route.

#Express (4 and 5)

app.use(telltale.express());                                          // early: records every request
app.post('/v1/invoices', requireAuth, telltale.protect(), createInvoice);   // a protected route, after your auth

The route template is read from Express (req.baseUrl + req.route.path, for example /v1/invoices/:id) when the response finishes.

#Next.js route handlers (App Router)

// app/api/invoices/[id]/route.js
import { telltale } from '@/lib/telltale';
export const GET = telltale.next(async (request, context) => Response.json(await loadInvoice(context.params)), { route: '/api/invoices/[id]' });

Pass the file's route as route; a route handler doesn't know its own template. On Vercel, set trustProxy: 1 so the client address comes from X-Forwarded-For. In a serverless function, call await telltale.flush() before it returns, or hand it to the platform (waitUntil(telltale.flush())).

#Hono

app.use(telltale.hono());
app.post('/v1/invoices', requireAuth, telltale.honoProtect(), createInvoice);

On Cloudflare Workers, flush with c.executionCtx.waitUntil(telltale.flush()).

#Fastify (4 and 5)

await fastify.register(telltale.fastify);

The plugin applies to the whole instance. The route template is Fastify's (request.routeOptions.url). Protected routes are checked in a preHandler hook.

#Route templates

Telltale stores the route template, never the path a request used and never a query string.

1. Your own route: req => '/v1/invoices/:id' function wins, when you give one.
2. Otherwise the framework's route (Express, Fastify, Hono, or route for Next.js), cleaned to the characters Telltale accepts (regular-expression groups such as :id(\\d+) are removed).

3. Otherwise the built-in normaliser: the query and fragment are dropped, and a segment is kept only when it reads like a word (a letter first, at most two digits, not a hex run, not a prefixed ID). Numbers, UUIDs, ULIDs, hashes, prefixed IDs such as inv_0 or cus_NffrFeUfNV2Hib, email addresses, slugs with digits and encoded text become :id. So /v1/invoices/12345?secret=x and /v1/invoices/inv_0 are both recorded as /v1/invoices/:id. At most 16 segments.

   Changed in @telltale/api 1.0.2: prefixed IDs (a short word, an underscore, then a value with a digit or mixed case) and UUIDs written with few digits now become :id; 1.0.1 kept them, so a route such as /v1/invoices/inv_0 was recorded once per ID. Every other route is recorded exactly as before. Routes already recorded keep their old name; new calls from 1.0.2 are recorded under the template.

On Node's own http server, pass route. Plain node:http has no router, so without route every path goes through the normaliser, and a short ID that reads like a word stays as it is: /v1/reports/r1 is recorded as /v1/reports/r1, not /v1/reports/:id. Such a route then never matches a rule you saved for GET /v1/reports/:id (the call is not checked) and each ID shows as its own route. Give telltale.node(handler) a route function (route: req => matchMyRoutes(req.url)) that returns your template. The dashboard warns in Tools › All tools when a Node route looks raw.

Each process keeps at most maxRoutes distinct templates (default 300); a new one after that is recorded as /:other. The server refuses a route that still looks like it carries a value (three or more digits in a row, a UUID, a long hex run, a long token with digits) and reports it in Is it working?.

#Identity

identify(req) returns { accountId, userId } from your own authentication. Send opaque IDs only, never an email address or a name.

• It runs after your handler (so your auth middleware has set the user), or before it for a protected route.
• A call is chargeable only when your server named its account (or an agent token did) and the rest of the chargeable rule holds (below). A call without an account is counted, never chargeable.
• Identified users are counted once across channels. A person your server identified in the browser, through your MCP server and through your API is one identified user that month on Telltale's plans.

#Privacy: what is and isn't sent

Sent to POST /api/v1/api-calls (server key) in batches. The batch:

Each call:

Telltale refuses any other field (per call, reported back as rejected; the rest of the batch is kept).

Never sent (unless you turn on Deep insights and list body or query fields, and even then never headers or credentials): request or response bodies, query values, the raw path, other headers, cookies, Authorization values, your own tokens and session IDs, and the user-agent string. The middleware sends no diagnostics about itself anywhere and never writes to stdout; debug: true (or TELLTALE_DEBUG=1) writes shapes-only lines to stderr or to your own function (debug mode).

#Agent evidence material: used once, never stored

To tell whether an agent made a call, the middleware forwards a little more, inside evidence. Telltale uses it while it records the batch and keeps only the result (the agent's name, how we know, the confidence and a network label such as "cloud provider"):

The address, the signature headers and the hash are never stored, logged or returned, as with Telltale's own traffic.

#Data stays with you

To keep the full requests for your own debugging, pass them to your own logs or OpenTelemetry. Telltale gets none of it:

createTelltaleApi({ /* … */, dataStaysWithYou: (call) => logger.info({ route: call.route, status: call.status, ms: call.durationMs }) });

#Deep insights (opt in, owner-enabled)

Off by default. With deepInsights: {routes: {'POST /v1/invoices': {body: ['amount'], query: ['expand']}}} and the site owner's switch on, the middleware sends the fields you list for calls that showed agent evidence; Telltale stores them only for AI agent calls, for 7 to 30 days. Headers, cookies, Authorization, tokens and other credentials are never sent or stored, whatever you list. See Deep insights.

Agents known only by their network address are not captured. "Agent evidence" here means a signal the middleware can see on the request itself: a Web Bot Auth signature, a declared agent name in the user agent or a header, or a Telltale agent token. An agent that Telltale recognises only by its address (an AI provider's published egress range, "Published IP range") is identified on Telltale's side after the call has been sent, so the middleware never had a reason to send that call's fields, and none are captured for it. This is deliberate: the middleware cannot tell such a call from a person's, and people's request bodies stay on your server. The call itself is still recorded, counted and shown as an AI agent call.

#How Telltale knows it was an agent

Strongest first. The first that applies names the call:

Verified (published IP range) means the call named its agent and its address is in that agent's own published list; Published IP range means only the address matched an AI provider's list, with no name to check.

• A declared name whose list was fresh and did not contain the address is Unknown, not an agent: someone may be borrowing the name.
• An address in an AI agent provider's published egress list is High confidence on its own: the provider publishes those addresses as its own agents' traffic, and an API call has no browser and no person behind it. (On a web page the same address never makes a session an AI agent; it only stops Telltale from calling it a person.)
• A cloud or data-centre address alone is not agent evidence. It is kept as a network label only.
• Medium confidence still shows as "AI agent", is held instead of denied at a protected route (unless your site blocks medium confidence) and is never chargeable.
• Confidence is a band from what backs the call, never a probability.

#Sampling high-volume APIs

createTelltaleApi({ /* … */, sampleRate: 0.1 });

Sampling applies only to calls with no agent signal the middleware can see (no signature, no declared name, no agent token) and no rule check. Those calls are kept at the rate you set and carry it, so the route counts in the dashboard are estimates. Every call with a visible signal, and every protected call, is always sent. A sampled call that Telltale later names by its network is recorded but never chargeable, because its count is an estimate. Leave out health checks and static files with skip: req => ….

#Rules for protected routes

Name the routes that should ask for your rule (Control › Rules) before your handler runs:

createTelltaleApi({
  /* … */,
  protect: {
    routes: [
      'POST /v1/invoices',                                                        // a write: fails closed when Telltale can't be reached
      { route: 'GET /v1/reports/:id', whenUnreachable: 'closed' },
      { route: 'DELETE /v1/invoices/:id', actionId: 'delete_invoice' },           // your own rule name
    ],
    // whenUnreachable: 'open' | 'closed' | { read, write }, decideTimeoutMs: 1500
  },
  onHold: async ({ decisionId, method, route, accountId, userId, req }) => {
    const ok = await askThePersonInYourApp(userId, route);   // your own step-up
    return ok ? { result: 'passed', method: 'own_approval' } : 'failed';
  },
});

• Control › Rules lists the routes seen through your API, marked "API". Save a rule there; it is kept under the route's action ID (derived from the method and route, or the actionId you gave).
• The branch of the call's evidence decides: AI agent for any agent evidence, Unknown otherwise. There is no Human branch on this channel. A protected route with no saved rule follows the defaults: AI agent Hold for review, Unknown Allow (until you save a rule that holds or denies it).
• Medium confidence (a Declared name) is held for review instead of denied, unless your site blocks medium confidence.
• Agent tokens: issue tokens with apiRoutes: ['GET /v1/reports/:id'] (Approved route for agents). A valid token names the account; in scope for the route, it turns a hold into allow. A Deny rule still denies.
• Deny: your handler doesn't run. The agent gets 403 {"error": "agent_not_allowed"}.
• Hold for review: your handler doesn't run yet. With onHold, your own step-up runs and, if it passes, the call goes ahead. Otherwise the agent gets 403 {"error": "approval_required", "decisionId": …}; once a teammate approves it in Control › Approvals › Waiting or your step-up passes, the agent's next try for the same route and account runs (once, within 15 minutes). A call with no account is never let through on an earlier approval: nothing ties one anonymous caller to the next (many share an address), so it is held again unless your own step-up passes for that call.
• Telltale unreachable: the check waits at most 1.5 seconds. Writes (POST, PUT, PATCH, DELETE) fail closed by default (503 {"error": "check_unavailable"} with Retry-After: 60); reads fail open. Change it per route or for all with whenUnreachable.
• Unknown and allowed calls are ordinary traffic and leave no decision record.
• A rule decision is evidence that Telltale's rule allowed the call. It is not authorization: your server still checks what the account and user may do.

#The decide and step-up endpoints

The middleware calls these for you; any language can call them with the server key:

• POST /api/v1/api-calls/decide with {method, route, actionId?, accountId?, userId?, evidence?, approvedDecisionId?} answers {decision: allow | review | deny, basis: rule | default_rule | agent_token | approval, verdict: agent | unknown, agent: {name, howWeKnow, confidence} | null, actionId, route, decisionId?, heldInsteadOfDeny?, stepUp?, accountId, userId}. verdict is never human on this channel: a server-to-server call carries no evidence of a person, so a call without agent evidence is unknown. A hold comes back as decision: "review" (shown in the dashboard as Waiting for a decision).
• GET /api/v1/api-calls/decisions/{id} answers the state of a held call.
• POST /api/v1/api-calls/decisions/{id}/step-up with {result: passed | failed, method?: passkey | mfa | turnstile | own_approval | other} settles a hold with your own check; passed approves it for one use within 15 minutes.

#Billing

An API call is chargeable when all of these hold: your server (or an agent token) named the account, the evidence is high confidence, the call ran (not refused) and it was not sampled. Every other agent call is counted and shown, never chargeable. Telltale's own plans count identified users a month, once across channels, never calls (Pricing).

#Batching and outages

Calls are queued in memory and sent in batches of up to 200 every five seconds. Network errors, 408, 429 and 5xx answers are retried with growing waits (up to a minute, honouring Retry-After), with the same batchId, so a batch whose answer was lost is never counted twice. Any other refusal drops the batch, logged once with debug: true. The queue holds 20,000 calls; past that the oldest are dropped and counted ("dropped" in Is it working?). A Telltale outage never slows or fails a request. Only protected routes wait, and only up to their timeout.

Call close() on shutdown and flush() at the end of a serverless invocation; calls still queued when a process is killed are lost (nothing is kept on disk). The server accepts up to 1,200 batches and 12,000 rule checks a minute per Site; a 429 just makes the middleware wait.

#Where it shows in the dashboard

• Settings › Channels › API: framework snippets and Is it working? (waiting for the first call, working, or quiet), with the middleware version and framework, the last batch, dropped calls and the last rejected field.
• Channel split on Home, the agent report and Charge › Usage: browser, MCP server and API.
• Control › Rules: API routes beside your protected actions and MCP tools.
• Accounts › All accounts: ranked by agent activity across channels (browser agent minutes plus MCP and API agent calls), so an account whose agents only use your API is listed too.
• Session drawer: an agent's API calls grouped into a session (account, user and agent, split after 30 idle minutes), with a timeline of route, outcome and time. No content.
• Issues: routes whose agent calls run longer than your slow-call limit (Slow tool calls, 30 s by default) or answer more than your token limit (Oversized responses, 20,000 tokens by default), beside the errors. Set both limits, for the Site or per route, in Issues › Limits. Neither changes error counts.
• Tools › All tools: each route's agent calls, error rate and p50/p95 by agent, plus all calls (agent or not) with "at most" times; filter by agent or by a tag (tags: req => ({ plan: req.user?.plan })). Custom events (telltale.event('invoice.paid', { accountId })) are counted there too. The bell tells you when a route starts failing for agents and when an account makes its first agent call. See Custom events, tags and debug mode.

#Troubleshooting

• "Waiting for the first call" stays on. Check the server key (a publishable ao_pk_ key is refused) and that your server can reach https://app.trytelltale.dev. Turn on debug: true and look at stderr.
• A route is rejected as "looks like it carries a raw value". Your framework or route function sent a real path such as /v1/invoices/12345. Return the template (/v1/invoices/:id) or let the built-in normaliser do it.
• Routes show as /:other. More than maxRoutes distinct templates in one process, usually because raw paths are being sent. Fix the template, or raise maxRoutes.
• Every call is Unknown. Expected for people and for agents that don't identify themselves. Behind a proxy or load balancer, set trustProxy (or clientIp) so the address is the client's, not the proxy's.
• Calls but no accounts. identify returned nothing: it runs after your handler, so check what your auth middleware sets on the request.
• A signed agent isn't Verified. A signature that covers headers or the query beyond the components listed above is not forwarded. A batch that arrives after the signature expired can't verify either; keep the default five-second interval.
• Counts look round on a busy route. Sampling is on: the route's counts are estimates.

See Approved route for agents for agent tokens, Telltale for MCP servers for the MCP channel, and Agent-usage ledger for how calls are counted.