Observe API

fetch('https://observe.tansohq.com/api/events/ingest', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.OBSERVE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    events: [{
      eventName: 'chat',
      customerReferenceId: user.id,
      featureKey: 'ai_chat',
      model: 'gpt-4o-mini',
      modelProvider: 'openai',
      inputTokens: res.usage?.prompt_tokens,
      outputTokens: res.usage?.completion_tokens,
    }],
  }),
}).catch(console.error)

Self-serve signup

Create an account and get an API key in one call. No auth required. Rate limited to 3/hr per IP.

curl -X POST https://observe.tansohq.com/api/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@yourapp.com",
    "scopes": ["usage.read", "events.write", "proxy.chat"],
    "budget_cents": 5000,
    "budget_period": "month"
  }'

Response: { "key": "obs_...", "scopes": [...], "budget_cents": 5000 }

Field	Default	Description
email	required	Account email
scopes	["usage.read", "billing.read"]	Key scopes (see table below)
budget_cents	null (unlimited)	Per-key LLM spend cap
budget_period	null (lifetime)	"month" or "day"
expires_in_seconds	null (never)	Auto-expire the key

Key introspection

curl https://observe.tansohq.com/api/sdk-keys/me \
  -H "Authorization: Bearer obs_..."

Returns your key's scopes, budget remaining, and expiry. Call this before expensive operations to check your budget.

Plan and limits

curl https://observe.tansohq.com/api/plan \
  -H "Authorization: Bearer obs_..."

Returns your account plan, per-feature limits, current usage, and remaining quota.

Ingest events

curl -X POST https://observe.tansohq.com/api/events/ingest \
  -H "Authorization: Bearer obs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "eventName": "chat",
      "customerReferenceId": "acme-corp",
      "featureKey": "ai_chat",
      "model": "gpt-4o-mini",
      "modelProvider": "openai",
      "inputTokens": 150,
      "outputTokens": 80
    }]
  }'

Requires events.write scope. Batch up to 1000 events per request. Cost auto-computed from model + tokens.

Scopes

Scope	Access	Signup?
proxy.chat	LLM proxy/gateway	Yes
usage.read	Features, analytics, simulations	Yes
events.read	Events, traces, aggregations	Yes
events.write	Ingest events, manage keys	Yes
customers.read	Customers, subscriptions, cohorts	Yes
billing.read	Plan, entitlements, cloud costs	Yes
recommendations.read	Optimization recommendations	Yes
models.read	Model pricing and stats	Yes
usage.write	Modify features, simulations	No
customers.write	Modify customers, upload data	No
billing.write	Cloud cost integrations	No
alerts.read	Alert rules and history	No
alerts.write	Create/modify alert rules	No
admin	Full access	No

Scopes marked "No" require a human to create the key via POST /sdk-keys with a Clerk session.

Management API

Analytics

GET	/api/analytics/overview	Dashboard KPIs
GET	/api/features	Features with cost/revenue stats
GET	/api/customers	Customers with margins
GET	/api/events	Paginated event list
GET	/api/models	Model cost stats

Alerts

GET	/api/alerts	List alert rules
POST	/api/alerts	Create alert rule
DEL	/api/alerts/:id	Delete alert rule

Recommendations

GET	/api/recommendations	Optimization recommendations
POST	/api/recommendations/compute	Trigger recommendation engine

Full reference

See llms.txt for complete endpoint list, event schema, tracing, revenue attribution, and integration paths (direct ingest, gateway headers, SDK auto-wrap).