Verify agent tracking

Developers and coding agents can check a site without database access. Use two separate checks: public conformance for what the site serves, and authenticated receipt verification for what Kismet stored.

Release status

The receipt API, SDK method and OAuth tool below are preview source contracts. They require the matching backend and OAuth relay deployments and a compatible SDK release exporting client.telemetry.verifyAgentTracking. The published 0.2.0-beta.1-poppy02.20261018.2 does not contain that method. Check deployment and tools/list before use; installation does not activate access or grant permissions.

Check public pages

npx kismet check https://your-staging-site.example --env staging --json

Use the actual served environment. For a static production export, use npx kismet check ./out --env production --json. Do not pass a .next directory. kismet verify additionally runs the configured recipe checks. Blocking findings fail the command; warnings remain visible but do not make its exit code nonzero. These checks do not inspect persisted receipts or authenticate a personal agent.

Send synthetic probes

Use only public discovery or document URLs, never guest data, login links, tokens or cookies. Generate a fresh UUID probeId for each run and add kismet_probe=<probeId> to every URL. Give each distinct request a unique URL, including separate GET and HEAD probes. Record the exact URL and full original User-Agent; use null only when no User-Agent header was sent.

Test installed llms.txt, llms-full.txt when present, public Markdown, and Poppy/MCP discovery. Include known, unknown and missing UAs. To test a warm cache, deliberately repeat one exact URL and UA, then set its expectedReceipts to the number of requests sent. HTTP method, status, empty HEAD bodies, cache HITs, and absence of Set-Cookie must be checked at the HTTP client: receipt storage does not prove them.

Wait for asynchronous ingestion before verifying. Set since just before probing and until just after it. The window is half-open (since <= timestamp < until), at most 30 minutes, and within the last day. There are at most 32 distinct URL/UA pairs, each expecting zero to five receipts. A zero expectation is useful for a deliberately unconfigured ownership-proof route. It proves only no matching receipt in this collection/environment/window, not global absence of sessions or traffic.

Verify through manager OAuth MCP

Connect the Kismet Developer MCP and sign in with an ADMIN or DEVELOPER account for the collection. Call verify_agent_tracking with installation_id and input matching the SDK example below. Infrastructure rechecks current collection authority, application/installation state and a collection-wide telemetry.read grant. No server key needs to be issued or pasted into chat.

URLs must use exact HTTPS origins already registered on that installation. TEST installations can inspect only non-production environments; LIVE can inspect only production. Domain verification or a manifest does not grant telemetry access. Anonymous, guest and machine-key MCP callers cannot use this manager tool; server integrations use REST/SDK instead. Missing grants must follow the separately approved access setup, not automatic escalation.

Verify through a server SDK

import { createKismetClient, KISMET_LIVE_API_BASE_URL } from '@kismet-tech/sdk/server';

const client = createKismetClient({ baseUrl: KISMET_LIVE_API_BASE_URL }); // KISMET_SECRET_KEY in the server secret store
const result = await client.telemetry.verifyAgentTracking({
  probeId: '11111111-1111-4111-8111-111111111111',
  environment: 'staging',
  since: '2026-10-19T11:50:00Z', // replace with this run's timestamps
  until: '2026-10-19T12:00:00Z',
  probes: [{
    id: 'llms-unknown-warm',
    pageUrl: 'https://your-staging-site.example/llms.txt?kismet_probe=11111111-1111-4111-8111-111111111111&request=1',
    userAgent: 'YourSyntheticAgent/1.0',
    expectedReceipts: 2,
  }],
});
if (!result.ok) throw new Error(JSON.stringify(result));

Use the server entry point and a restricted server credential with collection-wide telemetry.read. The key carries its collection; a collection override is only a locator, never authority. Browser and publishable clients do not expose this method.

REST uses POST /v1/developer/collections/{collection}/telemetry/agent-verification with the same JSON input and Bearer server credential. It is read-only; POST keeps full probe URLs and UAs out of query strings. Responses and SDK requests use no-store. Do not log request bodies in your own proxy.

Interpret results

The response returns each supplied probe ID, expected/matched counts, server/fetch/view counts, human-session contamination counts and diagnostic codes. It never returns raw URLs, UAs, events, IPs, guest identifiers or session values.

Diagnostic	Action
MISSING_RECEIPT	Allow ingestion to settle, then retry the same bounded window. Check middleware runs before static/CDN returns.
DUPLICATE_RECEIPT	Check for overlapping middleware, route and edge capture.
UNEXPECTED_RECEIPT	An expected-zero control was captured; inspect its route boundary.
NOT_SERVER_FETCH	A receipt was not a server-side fetch. Check the adapter integration.
HUMAN_SESSION_PRESENT	Synthetic document traffic acquired a human-session reference. Do not claim clean acceptance.
INCOMPLETE_EVIDENCE	The 256-row safety bound was exceeded. Narrow the probe set/window; truncated evidence never passes.

ok requires complete evidence and every probe passing. A missing receipt is not success merely because the request returned HTTP 200. 400 means invalid input/window; 401 inactive or missing credential; 403 missing grant, wrong environment or origin; 404 unavailable collection; 429 quota; 503 unavailable authority or storage. Fail closed and retry transient failures with bounded backoff.

This check does not prove consent, returning-visitor recovery, booking attribution, provider delivery, global cross-collection absence, or Poppy session acceptance. Poppy discovery and authenticated agent issuance/renewal remain separate acceptance steps.