Quick Start

Install the SDK and start logging AI traffic in under 5 minutes.

Install

bash

npm install apptvty
# or
pnpm add apptvty

Node.js ≥ 18 required (uses native fetch).

Get credentials

Run the CLI to register your site and write credentials to your env file automatically. No account or email needed — a wallet is created for you.

bash

# Interactive (human)
npx apptvty init

# Non-interactive (agent / CI)
npx apptvty init --domain mysite.com --framework nextjs --non-interactive

This writes APPTVTY_API_KEY and APPTVTY_SITE_ID to .env.local (Next.js) or .env (Express). CLI reference → or Programmatic Onboarding →

Add to your app

Next.js (App Router) full guide →

middleware.ts

import { withApptvty } from 'apptvty/nextjs';

export default withApptvty({
  apiKey: process.env.APPTVTY_API_KEY!,
  siteId: process.env.APPTVTY_SITE_ID!,
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

app/query/route.ts

import { createNextjsQueryHandler } from 'apptvty/nextjs';

export const GET = createNextjsQueryHandler({
  apiKey: process.env.APPTVTY_API_KEY!,
  siteId: process.env.APPTVTY_SITE_ID!,
});

Express full guide →

server.ts

import express from 'express';
import { createExpressMiddleware, createExpressQueryHandler } from 'apptvty/express';

const app = express();
const config = {
  apiKey: process.env.APPTVTY_API_KEY!,
  siteId: process.env.APPTVTY_SITE_ID!,
};

app.use(createExpressMiddleware(config));
app.get('/query', createExpressQueryHandler(config));

Verify it's working

Open your dashboard (the URL printed by the CLI), send a test request with a known AI user-agent, and watch the request appear in your analytics within seconds.

bash

# Simulate a GPTBot request
curl -A 'GPTBot/1.1' https://yoursite.com/

# Test the query endpoint
curl 'https://yoursite.com/query?q=What+does+this+site+do'

Configuration

All middleware and handler functions accept an ApptvtyConfig object.

Field	Type	Default	Description
`apiKey`	string	—	Required. Your API key (ak_live_...)
`siteId`	string	—	Required. Your site ID (site_...)
`baseUrl`	string?	https://api.apptvty.com	API base URL override
`batchSize`	number?	50	Log entries per flush
`flushInterval`	number?	5000	ms between auto-flushes
`debug`	boolean?	false	Print API errors to console
`queryPath`	string?	/query	Path of the AEO endpoint on your domain

Next.js guide →

Middleware wrapping, App Router patterns

Query endpoint →

What agents see when they call /query