API and agent quickstart

Build with your coding agent, then measure one change in your own app. An Observe project is a private app workspace; it is separate from a public builder project. Publishing a project never publishes these measurements.

1. Connect your app. In Build, select a project and open Connect app. Choose Node.js 20.19+ or Python 3.10+, download the private SDK and verify its checksum. Node captures supported OpenAI and Anthropic requests after integrating its fetch wrapper; Python records only calls you explicitly instrument. The private packages are not published to npm or PyPI.
2. Check a recorded request. Keep TOKENS_OBSERVE_INGEST_URL and TOKENS_OBSERVE_API_KEY in your server environment. Consume the response and flush before shutdown, then refresh Requests for the same project. Python uses observer.flush(timeout=5) and reports incomplete delivery when events are active, pending, failed or dropped; setup or invalid caller metadata can raise. A copied setup or old request history does not prove a new connection.
3. Compare one change. Compare with the Node.js or Python SDK. Replace the example with your actual baseline, candidate, cases and required checks. Python comparisons support macOS or Linux and synchronous, non-streaming OpenAI or Anthropic calls through its provided transport; Python post-fix verification requires a new patch-bound comparison. Review source files and provider-call limits before execution. Refresh Comparison results to inspect both arms, failed checks and losing trials; unknown cost is not zero.
4. Verify locally. Review an eligible handoff and its exact patch before applying it manually. Run the app's relevant tests and a new comparison with fresh held-out cases. Keep failed results; a comparison does not apply or deploy a fix.

These commands install the Node.js comparison SDK. For Python request metadata or workflow comparisons, select Python in Connect app and use its checksum-pinned wheel and instructions.

# Download in Connect app and verify its displayed checksum first.
# Put the downloaded SDK archive in this directory first.
node -e "const fs=require('node:fs'),crypto=require('node:crypto');if(crypto.createHash('sha256').update(fs.readFileSync('./tokensand-observability-0.5.13.tgz')).digest('hex')!=='2e8b21438f1a574b4f3f78c5564defedbec8e08a219a74d69b4205bda554db4d')throw new Error('SDK checksum mismatch; download again.');console.log('SDK checksum verified');" &&
npm install --offline --ignore-scripts --no-audit --no-fund ./tokensand-observability-0.5.13.tgz

For a local-only Node comparison, obtain the private SDK as an authorized owner and install it with the checksum commands above. Save this as local-comparison.mjs and run node ./local-comparison.mjs; it reports 12 passing runs. Execution needs no ingestion key or collector. Results stay in memory and do not appear in Build as hosted receipts, usage, costs or savings. Trusted callbacks are not sandboxed. The direct API does not freeze sources or prevent reruns; CLI plan and run --local freeze declared sources and claim each plan once.

import { runLocalWorkflowExperiment } from "@tokensand/observability/workflows";

const result = await runLocalWorkflowExperiment({ definition: {
  cases: [{ id: "small", input: 2 }, { id: "large", input: 5 }],
  checks: [{ id: "correct", label: "Correct result" }], repetitions: 3, timeoutMs: 1000,
  baseline: input => input * 2,
  candidate: input => input + input,
  evaluate: ({ input, output }) => ({ correct: output === input * 2 }),
} });
console.log(JSON.stringify({ state: result.state, runs: result.runs.length,
  passed: result.runs.filter(run => run.status === "ok" && run.checks.correct === true).length }));

import json
from tokensand_observe.workflow import compare_local

result = compare_local(
    cases=[{"id": "small", "input": 2}, {"id": "large", "input": 5}],
    checks=[{"id": "correct", "label": "Correct result"}],
    baseline=lambda value: value * 2,
    candidate=lambda value: value + value,
    evaluate=lambda value, output, variant: {"correct": output == value * 2},
)
print(json.dumps({"state": result["state"], "runs": len(result["runs"]),
    "passed": sum(run["status"] == "ok" and run["checks"]["correct"] is True
                  for run in result["runs"])}))

The SDK does not automatically collect raw prompts, outputs or source patches. Workflow metadata can include caller-supplied text; your configured provider receives the requests your callbacks send. Keep workflow titles, check labels and check versions free of sensitive data; detection is not guaranteed. Keep keys, private content and personal data out of all metadata. Observe uses a separate server-only ingestion key; DAI_TOKEN and company tracking keys cannot replace it. Availability remains account-gated.

For supported OpenAI calls, the SDK may record the served service tier reported in a successful response. This is SDK-reported, not independently verified billing. Missing tiers remain unreported; existing standard-rate estimates are assumptions and can exclude regional, tool, media and negotiated charges. Unsupported pricing remains unknown.

To compare these estimates with provider costs, an authorized account owner can check the OpenAI Costs API for the same project and UTC days. These are project-day aggregates, not bills for individual requests or runs; reporting may be delayed or adjusted. Never share an admin key with Tokens&. The source checkout also has an offline scripts/observe-openai-costs-report.mjs helper for a locally saved response; it is not included in the downloaded SDK and cannot authenticate the file or establish a final bill.

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 50 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.

Install the versioned server-side SDK from Tokens&amp.; it is not published on public npm. trackUsageReceipt supports model, API, spend and build receipts. Package integrity and delivery limits.

npm install https://tokensand.com/packages/tokensand-adoption-0.1.1.tgz

Queued events survive failed uploads within the running process; flush and inspect the result before shutdown. The queue is bounded and held in memory, so a process crash can lose pending events. Preserve event IDs and original timestamps when replaying from your own durable source.

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.");
}

Use the versioned SDK installation above, or send the same receipt through the REST quickstart.

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 https://tokensand.com/packages/dev-adoption-cli-0.1.64.tgz mcp serve --api https://tokensand.com

# Claude Code registration
claude mcp add --transport stdio tokensand -- npx -y https://tokensand.com/packages/dev-adoption-cli-0.1.64.tgz 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.

For private enterprise reads, an owner/admin creates a product-scoped Agent read-only key in native Enterprise Settings. Put it in DAI_ENTERPRISE_TOKEN in the agent environment and select --mode enterprise. Never put credentials in prompts or URLs. Call get_enterprise_context, then get_enterprise_report or get_enterprise_actions with an authorized productId. Free context covers configuration; reports and saved actions retain paid plan gates. These tools cannot ingest, export, approve or execute.

enterprise_session_brief analyzes supplied or sample metrics by default. With live:true and productId, it returns the canonical live report without sample fallback. Browser login and context labels do not grant MCP access. Preserve grades, nulls, scope, window and result limits; an output does not prove reconciled spend, provider delivery or measured ROI. Review approved actions in the workspace.