API Reference¶

Base URL for all endpoints: https://tokensor.dev

All authenticated endpoints require your Tokensor API key.

Authentication¶

Send your Tokensor key (ts_...) in one of these ways:

# Primary
curl https://tokensor.dev/v1/analytics/summary -H "X-Tokensor-Key: ts_..."
# Alternatively, provider SDKs:
curl https://tokensor.dev/v1/analytics/summary -H "Authorization: Bearer ts_..."

The proxy routes also accept provider-native key headers (x-api-key, x-goog-api-key) when they carry a ts_... value.

Health¶

Method	Path	Description
GET	`/health`	Liveness check.

Events (ingest)¶

Method	Path	Description
POST	`/v1/events/batch`	Ingest a batch of LLM call events for analytics.

Analytics¶

Method	Path	Description
GET	`/v1/analytics/summary`	Spend/token summary (`?days=`).
GET	`/v1/analytics/daily-totals`	Daily totals (`?days=`).
GET	`/v1/analytics/cost-by-model`	Cost grouped by model (`?days=`).
GET	`/v1/analytics/agents`	Per-agent cost rollups (`?days=`).
GET	`/v1/analytics/tools`	Tool call analytics.
GET	`/v1/stats/calls`	Call stats.

Findings & recommendations¶

Method	Path	Description
GET	`/v1/findings`	List detected inefficiency findings.
GET	`/v1/findings/{id}/recommendations`	Recommendations for a finding.
POST	`/v1/findings/{id}/recommendations`	Request recommendations for a finding.
POST	`/v1/findings/{id}/export-sample`	Export an approved sample.
PATCH	`/v1/findings/{id}/mark-fixed`	Mark a finding fixed.
PATCH	`/v1/findings/{id}/reopen`	Reopen a finding.
GET	`/v1/recommendations`	Batch recommendations (`?finding_ids=`).

Settings¶

Method	Path	Description
GET	`/v1/settings/account`	Account + integration status.
GET	`/v1/settings/connection-status`	Whether any LLM call has been recorded.
GET	`/v1/settings/integrations`	List supported key providers.
PUT	`/v1/settings/integrations/{provider}`	Save a provider API key (`openai`, `anthropic`, `opencode`).
DELETE	`/v1/settings/integrations/{provider}`	Remove a stored provider API key.
PUT	`/v1/settings/integrations/langfuse`	Configure Langfuse.
DELETE	`/v1/settings/integrations/langfuse`	Disconnect Langfuse.
PUT	`/v1/settings/integrations/helicone`	Configure Helicone.
DELETE	`/v1/settings/integrations/helicone`	Disconnect Helicone.
PUT	`/v1/settings/alerts/spend-threshold`	Set spend alert threshold.
DELETE	`/v1/settings/alerts/spend-threshold`	Clear spend alert threshold.
PUT	`/v1/account/keys`	Rotate your Tokensor API key.
DELETE	`/v1/account`	Delete your account.

Save a provider key:

curl -X PUT https://tokensor.dev/v1/settings/integrations/opencode \
  -H "X-Tokensor-Key: ts_..." \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-your-provider-key"}'

Transparent proxies¶

Method	Path	Upstream
POST	`/v1/proxy/openai/v1/chat/completions`	OpenAI
POST	`/v1/proxy/anthropic/v1/messages`	Anthropic
GET/POST	`/proxy/opencode/{channel}/v1/{operation}`	OpenCode Zen (`zen`) / Go (`go`)

The stored provider key is injected upstream automatically. Usage is recorded on every successful call.

Upstream keys¶

Method	Path	Description
GET	`/v1/upstream-keys`	Key connection status.
POST	`/v1/upstream-keys/{provider}`	Save an upstream key.
DELETE	`/v1/upstream-keys/{provider}`	Remove an upstream key.
POST	`/v1/upstream-keys/{provider}/test`	Test a key.

Proxy enforcement¶

Method	Path	Description
GET	`/v1/proxy/enforcement`	Daily spend ceiling + behavior.
PUT	`/v1/proxy/enforcement`	Set daily spend ceiling (`block` / `alert_only`).
GET	`/v1/proxy/stats`	Calls blocked / spend saved (7 days).

Billing¶

Method	Path	Description
GET	`/v1/billing/status`	Tier, quota usage, subscription status.
GET	`/v1/billing/checkout`	Checkout URL for a plan (`?plan=`).

OpenTelemetry traces¶

Method	Path	Description
POST	`/v1/otel/traces`	Ingest OTLP/HTTP JSON traces (signal-specific endpoint).
POST	`/v1/otel/v1/traces`	Alias for exporters that append `/v1/traces` to a base URL.

Exporters can use either the signal-specific endpoint (no path appended) or the base endpoint https://tokensor.dev/v1/otel with the standard appended /v1/traces:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://tokensor.dev/v1/otel/traces
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="X-Tokensor-Key=<your-api-key>"

Projects¶

Method	Path	Description
GET	`/v1/projects`	List projects.
POST	`/v1/projects`	Create a project.
DELETE	`/v1/projects/{project_id}`	Delete a project.

Webhooks¶

Method	Path	Description
POST	`/v1/webhooks/clerk`	Clerk auth webhook.
POST	`/v1/webhooks/paddle`	Paddle billing webhook.