Connect Obsivara to your AI agent

Give an AI agent an Obsivara API key and this page; it can wire up telemetry end-to-end.

This page is written for an AI agent. It contains exact endpoints, payloads, and verification steps with no ambiguity. Copy this URL — or the machine-readable version — into your agent's context.

Prerequisites

An obs_live_... API key with the ingest:write scope. Create one in the dashboard under Settings → API Keys.
Base URL: https://api.obsivara.com. All ingest routes are at /ingest/* — there is no /v1 prefix on ingest.
Auth header on every request: Authorization: Bearer obs_live_YOUR_KEY

Step 1 — Verify the key

Send a test event. A 202 response confirms the key is valid and has the right scope.

bash

curl -X POST https://api.obsivara.com/ingest/webhook/generic \
  -H "Authorization: Bearer obs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "run_started",
    "run_id": "verify-key-1",
    "asset_id": "my-agent",
    "name": "Key verification run",
    "input": "ping"
  }'

Expected response:

json

{ "source": "generic", "accepted": 1, "rejected": 0, "errors": [] }

202 — key works. Continue to Step 2.
401 — bad or missing key. Check the header format: Authorization: Bearer obs_live_...
403 — key exists but lacks ingest:write scope. Create a new key with that scope.

Step 2 — Instrument one workflow run

A run has three lifecycle events: run_started when the workflow begins, one or more llm_call events for each model call, and run_finished when it completes. Send them in order with the same run_id to tie them into one run.

Reuse the same run_id across all three calls to tie them into one run in the dashboard. asset_id is the thing you are monitoring — your agent name, workflow name, or prompt identifier. The run_id can be any string; Obsivara maps non-UUID values to a stable UUID automatically.

Event 1 — run_started

Body payload:

json

{ "event": "run_started", "run_id": "order-123", "asset_id": "support-agent", "name": "Support reply", "input": "where is my order?" }

Full curl:

bash

curl -X POST https://api.obsivara.com/ingest/webhook/generic \
  -H "Authorization: Bearer obs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "run_started", "run_id": "order-123", "asset_id": "support-agent", "name": "Support reply", "input": "where is my order?" }'

Event 2 — llm_call

Body payload:

json

{ "event": "llm_call", "run_id": "order-123", "provider": "openai", "model": "gpt-4o", "prompt_tokens": 312, "completion_tokens": 87, "total_tokens": 399, "cost_usd": 0.0048, "latency_ms": 1240 }

Full curl:

bash

curl -X POST https://api.obsivara.com/ingest/webhook/generic \
  -H "Authorization: Bearer obs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "llm_call", "run_id": "order-123", "provider": "openai", "model": "gpt-4o", "prompt_tokens": 312, "completion_tokens": 87, "total_tokens": 399, "cost_usd": 0.0048, "latency_ms": 1240 }'

Event 3 — run_finished

Body payload:

json

{ "event": "run_finished", "run_id": "order-123", "outcome": "success", "duration_ms": 3500, "total_cost_usd": 0.0048 }

Full curl:

bash

curl -X POST https://api.obsivara.com/ingest/webhook/generic \
  -H "Authorization: Bearer obs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event": "run_finished", "run_id": "order-123", "outcome": "success", "duration_ms": 3500, "total_cost_usd": 0.0048 }'

All three requests go to the same endpoint:

text

POST https://api.obsivara.com/ingest/webhook/generic

Step 3 — Confirm

Open app.obsivara.com, find support-agent (or your asset_id) on the inventory page, and open the run to see the trace, token counts, and cost. Runs appear within approximately one minute.

For a full verification checklist, see Verify it worked →

If you use a framework

The generic webhook above works with any stack. For framework-specific integrations:

n8n — add an HTTP Request node to any workflow
OpenTelemetry (OTLP) — point your OTel exporter at https://api.obsivara.com/ingest/otlp
LangSmith — forward runs via webhook
Langfuse — forward traces via webhook
JavaScript SDK — typed helpers for TypeScript projects (preview)

Machine-readable version

To fetch the complete connection guide in one request (no HTML), use:

bash

curl https://doc.obsivara.com/llms-full.txt

This plain-text file contains every endpoint, payload, and error table from this documentation — suitable for injecting directly into an agent's context window.