API and agent quickstart

1. 1. Create a tracking key. Open the company workspace, choose the product, and store the key on your server.
2. 2. Validate one event. Use the dry-run examples. Check accepted: true, the product, account and campaign mapping.
3. 3. Store and verify. Send an approved real event to /api/usage/track. Confirm tracked: true and its event ID, then find it in your workspace.

Use a stable source event ID as idempotencyKey; reuse it only for retries of that event. A retry with duplicate: true refers to the existing event. A 2xx response alone does not prove storage. An ignored product can return tracked: false.

These examples validate without storing an event. Replace sample identifiers and review the returned mapping before a real write.

# Set TOKENSAND_ADOPTION_KEY in your server environment first.
curl --fail-with-body https://tokensand.com/api/usage/track/dry-run \
  -H "Authorization: Bearer $TOKENSAND_ADOPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "event_name": "FIRST_API_CALL",
  "event_family": "activation",
  "developer_id": "dev_123",
  "account_domain": "customer.example",
  "product": {
    "id": "your-api",
    "name": "Your API",
    "type": "api"
  },
  "context": {
    "attribution": {
      "campaignId": "your-campaign-id",
      "source": "workshop"
    }
  },
  "idempotencyKey": "source-event-123"
}'

Base URL: https://tokensand.com. Read exact request and response schemas in OpenAPI.

401/403: verify token type and access. 400: correct the payload. 409: do not change an event under an existing idempotency key. 429: respect rate-limit headers before retrying. On an uncertain write, inspect what persisted before retrying. Reuse the same payload and key only where idempotency is documented.

Send event_name and one stable developer identifier. Organization tracking keys also require product and idempotencyKey (or event_id) for stored events. Add event_family for custom names.

account_domain

The customer account to match. Use the actual account, not the vendor sending the event.

context.attribution.campaignId

Your campaign identifier. A top-level campaignId is not part of the tracking schema.

occurredAt

ISO 8601 time of the real event; preserve it on replay. Do not invent retention timestamps.

projectId

Optional existing Tokens& project ID for linked project proof. Omit it when no project exists.

For Segment/PostHog-style input, map event to event_name, userId to developer_id, and campaign properties into context.attribution. Send the canonical payload above, not the raw CDP envelope. Batch requests use {"events": [...]}, up to 500 events.

The server-side SDK writes the tokensand-usage-receipt-v1 contract into metadata.usageReceipt. The calls below store events; validate your integration first. Metrics are illustrative and must be replaced with observed values.

@tokensand/adoption@0.1.0 is not available on public npm. These examples are reference-only for teams supplied with the SDK. Use the REST quickstart above for setup; do not install or import an unavailable package. With a supplied SDK, trackUsageReceipt supports model, API, spend and build receipts.

import { tokensand } from "@tokensand/adoption";

const adoption = tokensand({
  apiKey: process.env.TOKENSAND_ADOPTION_KEY!,
  baseUrl: "https://tokensand.com"
});

// This SDK call stores an event. Replace every illustrative value with measured usage.
const result = await adoption.trackUsageReceipt<{ tracked?: boolean; duplicate?: boolean; ignored?: boolean }>({
  receiptType: "model_call",
  product: { id: "your-model", name: "Your model", type: "model" },
  user: { id: "dev_123" },
  account: { domain: "customer.example" },
  workflow: { id: "support-agent", runId: "run_123", success: true },
  provider: "your-provider",
  model: "your-model",
  inputTokens: 1200,
  outputTokens: 340,
  costCents: 12,
  latencyMs: 820,
  success: true,
  idempotencyKey: "run_123:model-call-1"
});
if (!result.ok || (result.data?.tracked !== true && result.data?.duplicate !== true)) {
  console.warn("Usage receipt was not stored; check the tracking response.");
}

The SDK is not available on public npm. These examples are reference-only for teams supplied with the SDK; use the REST quickstart for setup.

trackMcpToolCall records MCP_TOOL_CALL_SUCCEEDED / MCP_TOOL_CALL_FAILED. Stable context: mcpServer, mcpTool, workflow.id, account.domain. Supply a unique execution ID for retries and measured metrics.

Place telemetry beside the real server-side tool call. Never send raw prompts, secrets, private payloads, private code. A single sample receipt does not justify a recommendation to keep or replace a stack.

import { tokensand } from "@tokensand/adoption";

const adoption = tokensand({
  apiKey: process.env.TOKENSAND_ADOPTION_KEY!,
  baseUrl: "https://tokensand.com"
});

// This SDK call stores an event. Use actual identifiers and measured metrics.
const result = await adoption.trackMcpToolCall<{ tracked?: boolean; duplicate?: boolean }>({
  product: { id: "your-agent", name: "Your agent", type: "agent" },
  user: { id: "dev_123" },
  account: { domain: "customer.example" },
  workflow: { id: "support-agent", runId: "run_123" },
  mcpServer: "your-server",
  mcpTool: "your-tool",
  requestCount: 1,
  latencyMs: 920,
  success: true,
  idempotencyKey: "run_123:tool-call-1"
});
if (!result.ok || (result.data?.tracked !== true && result.data?.duplicate !== true)) {
  console.warn("MCP receipt was not stored; check the tracking response.");
}

Send events from the partner server with a company tracking key. Validate one payload, then send activation when it happens and reconcile account and cost counters. CSV is a fallback when server events are unavailable.

Generate a developer workflow config from project setup. Skill imports require an unscoped workflow token with project:publish; project-scoped tokens are rejected. Use DAI_TOKEN, not a tracking key.

Parse a public SKILL.md, review the draft, then confirm creation with an idempotency key. This creates a private DRAFT. Public publishing remains a separate authenticated dashboard action after the install path is verified. Only import public content you may use; secrets and private repository files are not fetched.

# Replace this URL with a public SKILL.md that you own or may import.
# 1. Parse and review. This call returns persisted: false.
curl --fail-with-body https://tokensand.com/api/workflow/agent-skills \
  -H "Authorization: Bearer $DAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"skillUrl":"https://raw.githubusercontent.com/your-org/your-repo/main/SKILL.md"}'

# 2. After approval, create a PRIVATE draft. Reuse the key for retries of this import.
curl --fail-with-body https://tokensand.com/api/workflow/agent-skills \
  -H "Authorization: Bearer $DAI_TOKEN" \
  -H "Idempotency-Key: skill-import-your-stable-source-id" \
  -H "Content-Type: application/json" \
  -d '{"skillUrl":"https://raw.githubusercontent.com/your-org/your-repo/main/SKILL.md","confirm":true,"status":"DRAFT"}'

# Expect persisted: true, an agentHref and publicHref: null.
# Public publishing is a separate authenticated dashboard action after install verification.

Public reads are rate limited and aggregate. Preserve methodology, source labels and cohort suppression. Missing rows are not proof of no adoption.

curl --fail-with-body "https://tokensand.com/api/v1/adoption?period=30d&limit=10"

• Keep raw prompts, private notes and secrets out of metadata.
• Keep workspace data private and rotate exposed keys.
• Preserve first-party, public-source, sample, modelled and missing labels in reports.
• Small cohorts remain suppressed or insufficient; do not infer individual identities.
• Sponsor selection is self-reported until authenticated activation arrives. Retained proof requires a separate signal at least seven days later.

Start with the manifest and OpenAPI. Public lookup and build_brief need no token; private saved Build Packets require authorized workflow access. Installing MCP does not grant enterprise access.

# Public tools need no token. Pin the documented CLI version.
npx -y @dev-adoption/cli@0.1.12 mcp serve --api https://tokensand.com

# Claude Code registration
claude mcp add --transport stdio tokensand -- npx -y @dev-adoption/cli@0.1.12 mcp serve --api https://tokensand.com

# Set DAI_TOKEN through your host's secret environment only for private workflow access.

Use Tokens& build_brief for this project: [describe the product and constraints].
Return the stack choices, alternatives, available credits, cost and reliability risks,
and a Build Packet with the next implementation step and proof needed.
Separate public evidence from assumptions. Do not claim that setup proves adoption.

enterprise_session_brief analyzes supplied aggregate metrics or a labeled sample. It does not fetch live tenant data, even with enterprise credentials. Mode, organization and profile labels do not grant access. Its output does not prove reconciled spend or measured ROI; verify the underlying evidence.