Preparing page

Loading product graph, proof, and adoption context.

Preparing tokens&

Loading the next builder or enterprise surface.

Get proof pilot

Developer and agent docs

Integrate adoption proof without guessing the contract.

These docs give builders, enterprise teams, and AI agents the stable API, event, privacy, and context surface needed to send usage signals and read public adoption intelligence.

Create tracking key Open llms.txt

Quickstart

Dry-run one event

curl -X POST https://tokensand.com/api/usage/track/dry-run \
  -H "Authorization: Bearer tk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "FIRST_API_CALL",
    "event_family": "activation",
    "developer_id": "dev_123",
    "email": "builder@company.com",
    "product": {
      "id": "acme-api",
      "name": "Acme API",
      "type": "api",
      "version": "2026-05"
    },
    "account_domain": "company.com",
    "source": "SDK",
    "occurredAt": "2026-05-15T18:00:00.000Z",
    "idempotencyKey": "evt_123"
  }'

Usage tracking

Send product events from docs, SDKs, apps, agents, workflows, campaigns, credits, and events.

Public adoption graph

Read privacy-safe AgentRank and adoption rows for public tools, categories, and proof surfaces.

Agent-readable context

Give Codex, Claude, ChatGPT, Perplexity, and internal agents stable context through llms.txt.

Privacy contract

Aggregate public output, authenticated private workspaces, suppression thresholds, and no raw developer resale.

Enterprise integration quickstart

From tracking key to Revenue API in five steps.

This is the path an implementation engineer or AI coding agent should follow before building anything custom: prove the payload, send activation, map account domain, then export account/action evidence.

1. Create tracking key

Generate a company-scoped key in Tracking setup. Keep it server-side and rotate it if it leaves your control.

2. Dry-run event

Validate payload shape and account mapping with /api/usage/track/dry-run before storing production events.

3. Send activation event

Send activation and retention events with developer identifier, product, source, campaignId, and idempotencyKey.

4. Map account domain

Prefer account_domain over noisy company names so builder usage can become account demand and sales-ready exports.

5. Export or webhook to CRM

Use the Revenue API path: CSV, webhooks, account/action exports, and CRM/warehouse schemas after approval.

REST API

The minimum endpoint set worth documenting now.

We should not expose a huge fake docs portal before the product surface deserves it. The valuable docs today are tracking, public scores, agent context, auth, rate limits, and privacy behavior.

POST

/api/usage/track/dry-run

Validate one event without storing it.

Tracking key

POST

/api/usage/track

Store one adoption or usage event.

Tracking key

POST

/api/usage/track/batch

Store up to 500 events in one request.

Tracking key

GET

/api/v1/adoption

Read public privacy-safe adoption rows.

Public, rate-limited

GET

/api/v1/agent-rank

Alias for the public adoption score contract.

Public, rate-limited

Copy-paste examples

Use the same event contract from app code, scripts, CDP payloads, or agents.

These examples intentionally include account_domain, campaignId, product, and idempotencyKey because those fields turn raw events into attribution, account demand, exports, and executive proof.

Node / TypeScript

await fetch("https://tokensand.com/api/usage/track", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    event_name: "FIRST_API_CALL",
    event_family: "activation",
    developer_id: "dev_123",
    email: "builder@company.com",
    account_domain: "company.com",
    source: "SDK",
    campaignId: "cmp_launch_001",
    product: { id: "acme-api", name: "Acme API", type: "api" },
    idempotencyKey: "evt_123"
  })
});

Python

import requests

requests.post(
  "https://tokensand.com/api/usage/track",
  headers={
    "Authorization": "Bearer tk_live_xxx",
    "Content-Type": "application/json"
  },
  json={
    "event_name": "FIRST_API_CALL",
    "event_family": "activation",
    "developer_id": "dev_123",
    "email": "builder@company.com",
    "account_domain": "company.com",
    "source": "SDK",
    "campaignId": "cmp_launch_001",
    "product": {"id": "acme-api", "name": "Acme API", "type": "api"},
    "idempotencyKey": "evt_123"
  }
)

Segment/PostHog-style payload

{
  "type": "track",
  "event": "FIRST_API_CALL",
  "userId": "dev_123",
  "properties": {
    "event_family": "activation",
    "account_domain": "company.com",
    "product_id": "acme-api",
    "product_name": "Acme API",
    "campaignId": "cmp_launch_001",
    "source": "docs"
  },
  "context": {
    "traits": {
      "email": "builder@company.com"
    }
  }
}

Dry-run curl

curl -X POST https://tokensand.com/api/usage/track/dry-run \
  -H "Authorization: Bearer tk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "FIRST_API_CALL",
    "event_family": "activation",
    "developer_id": "dev_123",
    "email": "builder@company.com",
    "product": {
      "id": "acme-api",
      "name": "Acme API",
      "type": "api",
      "version": "2026-05"
    },
    "account_domain": "company.com",
    "source": "SDK",
    "occurredAt": "2026-05-15T18:00:00.000Z",
    "idempotencyKey": "evt_123"
  }'

Event contract

Send the event name humans use. Map it into a family agents can reason about.

Every event needs an event name and one developer identifier. Organization keys also send a product descriptor so adoption can be separated by API, model, SDK, workflow, agent, event, or docs surface.

Use idempotency keys for retries.

Use dry-run before first production send.

Prefer account_domain over noisy company names.

Avoid raw private notes in metadata.

Canonical event families

intent

Docs open, event RSVP, comparison, saved stack, pricing view.

evaluation

SDK init, API key created, demo project, benchmark, proof review.

activation

First API call, first successful workflow, project created.

retention

Returned D7/D30, repeated API calls, production-like usage.

expansion

Team added, account matched, more workflows or products adopted.

commercial

Credit claimed, perk redeemed, campaign sourced, opportunity created.

Public graph

Public reads should be boring, stable, and citable.

The public API returns aggregate rows with methodology links, ranking policy, cohort suppression, rate-limit headers, and no developer identities.

curl "https://tokensand.com/api/v1/adoption?category=ai-agents&period=30d&limit=10"

Agent docs

Agents need a compact truth source before they need a huge portal.

`llms.txt` and `llms-full.txt` tell external agents what tokens& is, which pages are canonical, which dashboards are private, and how to describe the public adoption graph.

llms.txt llms-full.txt

Auth

Tracking keys use Authorization: Bearer. Public graph reads are rate-limited.

Privacy

Private dashboards, API keys, raw developer records, and workspace data stay out of public agent context.

Integration

Codex, Claude Code, and internal agents can generate payloads from this page and validate them with dry-run.

Preparing page

Loading product graph, proof, and adoption context.

Developer and agent docs

Integrate adoption proof without guessing the contract.

These docs give builders, enterprise teams, and AI agents the stable API, event, privacy, and context surface needed to send usage signals and read public adoption intelligence.

Create tracking key Open llms.txt

Quickstart

Dry-run one event

curl -X POST https://tokensand.com/api/usage/track/dry-run \
  -H "Authorization: Bearer tk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "FIRST_API_CALL",
    "event_family": "activation",
    "developer_id": "dev_123",
    "email": "builder@company.com",
    "product": {
      "id": "acme-api",
      "name": "Acme API",
      "type": "api",
      "version": "2026-05"
    },
    "account_domain": "company.com",
    "source": "SDK",
    "occurredAt": "2026-05-15T18:00:00.000Z",
    "idempotencyKey": "evt_123"
  }'

Usage tracking

Send product events from docs, SDKs, apps, agents, workflows, campaigns, credits, and events.

Public adoption graph

Read privacy-safe AgentRank and adoption rows for public tools, categories, and proof surfaces.

Agent-readable context

Give Codex, Claude, ChatGPT, Perplexity, and internal agents stable context through llms.txt.

Privacy contract

Aggregate public output, authenticated private workspaces, suppression thresholds, and no raw developer resale.

Enterprise integration quickstart

From tracking key to Revenue API in five steps.

1. Create tracking key

Generate a company-scoped key in Tracking setup. Keep it server-side and rotate it if it leaves your control.

2. Dry-run event

Validate payload shape and account mapping with /api/usage/track/dry-run before storing production events.

3. Send activation event

Send activation and retention events with developer identifier, product, source, campaignId, and idempotencyKey.

4. Map account domain

Prefer account_domain over noisy company names so builder usage can become account demand and sales-ready exports.

5. Export or webhook to CRM

Use the Revenue API path: CSV, webhooks, account/action exports, and CRM/warehouse schemas after approval.

REST API

The minimum endpoint set worth documenting now.

We should not expose a huge fake docs portal before the product surface deserves it. The valuable docs today are tracking, public scores, agent context, auth, rate limits, and privacy behavior.

POST

/api/usage/track/dry-run

Validate one event without storing it.

Tracking key

POST

/api/usage/track

Store one adoption or usage event.

Tracking key

POST

/api/usage/track/batch

Store up to 500 events in one request.

Tracking key

GET

/api/v1/adoption

Read public privacy-safe adoption rows.

Public, rate-limited

GET

/api/v1/agent-rank

Alias for the public adoption score contract.

Public, rate-limited

Copy-paste examples

Use the same event contract from app code, scripts, CDP payloads, or agents.

These examples intentionally include account_domain, campaignId, product, and idempotencyKey because those fields turn raw events into attribution, account demand, exports, and executive proof.

Node / TypeScript

await fetch("https://tokensand.com/api/usage/track", {
  method: "POST",
  headers: {
    "Authorization": "Bearer tk_live_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    event_name: "FIRST_API_CALL",
    event_family: "activation",
    developer_id: "dev_123",
    email: "builder@company.com",
    account_domain: "company.com",
    source: "SDK",
    campaignId: "cmp_launch_001",
    product: { id: "acme-api", name: "Acme API", type: "api" },
    idempotencyKey: "evt_123"
  })
});

Python

import requests

requests.post(
  "https://tokensand.com/api/usage/track",
  headers={
    "Authorization": "Bearer tk_live_xxx",
    "Content-Type": "application/json"
  },
  json={
    "event_name": "FIRST_API_CALL",
    "event_family": "activation",
    "developer_id": "dev_123",
    "email": "builder@company.com",
    "account_domain": "company.com",
    "source": "SDK",
    "campaignId": "cmp_launch_001",
    "product": {"id": "acme-api", "name": "Acme API", "type": "api"},
    "idempotencyKey": "evt_123"
  }
)

Segment/PostHog-style payload

{
  "type": "track",
  "event": "FIRST_API_CALL",
  "userId": "dev_123",
  "properties": {
    "event_family": "activation",
    "account_domain": "company.com",
    "product_id": "acme-api",
    "product_name": "Acme API",
    "campaignId": "cmp_launch_001",
    "source": "docs"
  },
  "context": {
    "traits": {
      "email": "builder@company.com"
    }
  }
}

Dry-run curl

curl -X POST https://tokensand.com/api/usage/track/dry-run \
  -H "Authorization: Bearer tk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "FIRST_API_CALL",
    "event_family": "activation",
    "developer_id": "dev_123",
    "email": "builder@company.com",
    "product": {
      "id": "acme-api",
      "name": "Acme API",
      "type": "api",
      "version": "2026-05"
    },
    "account_domain": "company.com",
    "source": "SDK",
    "occurredAt": "2026-05-15T18:00:00.000Z",
    "idempotencyKey": "evt_123"
  }'

Event contract

Send the event name humans use. Map it into a family agents can reason about.

Use idempotency keys for retries.

Use dry-run before first production send.

Prefer account_domain over noisy company names.

Avoid raw private notes in metadata.

Canonical event families

intent

Docs open, event RSVP, comparison, saved stack, pricing view.

evaluation

SDK init, API key created, demo project, benchmark, proof review.

activation

First API call, first successful workflow, project created.

retention

Returned D7/D30, repeated API calls, production-like usage.

expansion

Team added, account matched, more workflows or products adopted.

commercial

Credit claimed, perk redeemed, campaign sourced, opportunity created.

Public graph

Public reads should be boring, stable, and citable.

The public API returns aggregate rows with methodology links, ranking policy, cohort suppression, rate-limit headers, and no developer identities.

curl "https://tokensand.com/api/v1/adoption?category=ai-agents&period=30d&limit=10"

Agent docs

Agents need a compact truth source before they need a huge portal.

`llms.txt` and `llms-full.txt` tell external agents what tokens& is, which pages are canonical, which dashboards are private, and how to describe the public adoption graph.

llms.txt llms-full.txt

Auth

Tracking keys use Authorization: Bearer. Public graph reads are rate-limited.

Privacy

Private dashboards, API keys, raw developer records, and workspace data stay out of public agent context.

Integration

Codex, Claude Code, and internal agents can generate payloads from this page and validate them with dry-run.