Getting Started

AI Agent Prompts

Are you using an AI assistant or editor (such as Cursor Composer, Windsurf, GitHub Copilot, ChatGPT, or Claude) to build your project? Copy these optimized prompts, paste them into your chat, and let the AI automatically inspect, refactor, and integrate Observyze for you.

Authentication

All requests to the Observyze Proxy Gateway or API endpoints require authentication using a project-specific API key. The key identifies which sandbox or production workspace receives the trace data.

API Key Format

Observyze uses a single, unified API key starting with the ob_ prefix to authenticate all requests, whether you are in development, testing, or production.

Loading Your Keys Safely

Add your Observyze API key to an environment variable file (like .env or .env.local):

OBSERVYZE_API_KEY=ob_5f8b9e1c2a3d4e5f6g7h8i9j

How to safely access and construct authentication headers in common stacks:

// Access safely via process.env
const apiKey = process.env.OBSERVYZE_API_KEY;

if (!apiKey) {
  throw new Error("Missing OBSERVYZE_API_KEY environment variable!");
}

# Access safely via standard os library
import os

api_key = os.environ.get("OBSERVYZE_API_KEY")
if not api_key:
    raise ValueError("Missing OBSERVYZE_API_KEY environment variable!")

Making Authenticated HTTP Requests

Pass your key in the HTTP Authorization header prefixed by Bearer.

curl -X GET "https://api.observyze.com/api/v1/traces" \
  -H "Authorization: Bearer ob_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

API Reference

Detailed references for all standard REST API endpoints. You can query traces, invoke circuit breakers, update settings, retrieve cost limits, and fetch alert rules directly.

SDKs & Libraries

The Node.js/TypeScript SDK provides explicit local wrappers for OpenAI, Anthropic, Gemini, Vercel AI SDK, LangChain, and LlamaIndex call boundaries, plus custom spans. Other languages can send validated traces through the HTTP ingestion API; no official Python SDK is present in this repository.

Proxy Gateway

The Proxy Gateway lets you record LLM telemetry without installing our custom NPM/Python libraries. You simply adjust the LLM client configuration by setting its baseURL to Observyze’s edge endpoint. Everything else stays unchanged!

OpenAI Gateway Setup

Change your client initialization to set baseURL to the Observyze proxy. Set your authorization header using your **Observyze Key** (loaded from environment variable OBSERVYZE_KEY). Make sure you have added your OpenAI api key to the dashboard settings under provider keys!

import OpenAI from 'openai';

const openai = new OpenAI({
  // Load Observyze API key
  apiKey: process.env.OBSERVYZE_KEY,
  // Point baseURL to proxy gateway
  baseURL: 'https://api.observyze.com/api/v1/proxy/openai/v1'
});

from openai import OpenAI
import os

client = OpenAI(
  # Load Observyze API key
  api_key=os.environ["OBSERVYZE_KEY"],
  # Point base_url to proxy gateway
  base_url="https://api.observyze.com/api/v1/proxy/openai/v1"
)

Anthropic Gateway Setup

Change your Anthropic client's baseURL to load through the proxy gateway:

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  // Use your Observyze API Key
  apiKey: process.env.OBSERVYZE_KEY,
  // Change base endpoint to proxy gateway
  baseURL: 'https://api.observyze.com/api/v1/proxy/anthropic'
});

Google Gemini Setup

You can easily route requests from the new official google-genai SDK through the proxy by setting the base URL and Authorization header in the HTTP options:

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({
  // Note: if you configured a BYOK key in Observyze, you can use a dummy key here.
  apiKey: process.env.GEMINI_API_KEY,
  httpOptions: {
    baseUrl: 'https://api.observyze.com/api/v1/proxy/google',
    headers: {
      'Authorization': `Bearer ${process.env.OBSERVYZE_KEY}`
    }
  }
});

from google import genai
from google.genai import types
import os

client = genai.Client(
  api_key=os.environ.get("GEMINI_API_KEY"),
  http_options=types.HttpOptions(
    base_url="https://api.observyze.com/api/v1/proxy/google",
    headers={"Authorization": f"Bearer {os.environ.get('OBSERVYZE_KEY')}"}
  )
)

Direct HTTP / cURL (Any Programming Language)

If you are using a programming language without official SDK support (such as Go, Rust, Ruby, or PHP), construct a raw POST request pointing to the gateway URL:

# OpenAI POST request
curl -X POST "https://api.observyze.com/api/v1/proxy/openai/v1/chat/completions" \
  -H "Authorization: Bearer $OBSERVYZE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Ping"}]
  }'

import requests

url = "https://api.observyze.com/api/v1/proxy/openai/v1/chat/completions"
headers = {
    "Authorization": f"Bearer {os.environ['OBSERVYZE_KEY']}",
    "Content-Type": "application/json"
}
payload = {
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Ping"}]
}

response = requests.post(url, headers=headers, json=payload)

Architecture & Security

Understanding how telemetry and circuit breakers execute under the hood is critical for enterprise security audits. Here is a breakdown of our security posture.

Evaluation & Safety

Run hallucination and safety evaluations, trigger custom trace replays, configure active circuit breakers, and run auto-detection systems.

Webhook Ingestion

The Observyze Webhook Ingest system allows any external tool, no-code platform, or custom backend to push trace data into Observyze using a simple HTTP POST request. This is an inbound integration — your system sends data to Observyze, and it appears in your dashboard as a trace.

Ingest Endpoint

Send a POST request to https://api.observyze.com/api/v1/ingest with your Observyze API key in the Authorization header. The endpoint auto-detects the payload format — a single event, a full trace with spans, or a batch of events.

Example 1 — Simple Event

The simplest integration: just POST a JSON object describing a single LLM call. Observyze will automatically assign a trace_id and store the event.

curl -X POST "https://api.observyze.com/api/v1/ingest" \
  -H "Authorization: Bearer ob_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Reply",
    "input": { "messages": [{"role": "user", "content": "How do I reset my password?"}] },
    "output": { "content": "Go to Settings → Account → Reset Password." },
    "model": "gpt-4o",
    "status": "success",
    "duration_ms": 843,
    "tokens": { "input": 45, "output": 18, "total": 63 },
    "cost": 0.00031,
    "tags": ["support", "production"],
    "user_id": "user_abc123"
  }'

# Response:
{ "accepted": true, "trace_id": "nw_a4b8f2c1d3e5" }

Example 2 — Batch Ingestion

Use POST /api/v1/ingest/batch to send up to 100 records. Use { events: [...] } for simple events or { traces: [...] } for complete SDK traces with spans.

curl -X POST "https://api.observyze.com/api/v1/ingest/batch" \
  -H "Authorization: Bearer ob_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "name": "Product Q&A",
        "input": { "messages": [{"role": "user", "content": "What is your return policy?"}] },
        "output": { "content": "Returns are accepted within 30 days." },
        "model": "gpt-4o-mini",
        "status": "success",
        "duration_ms": 510,
        "tokens": { "input": 22, "output": 11, "total": 33 }
      },
      {
        "name": "Sentiment Analysis",
        "input": { "text": "The product is great but shipping was slow." },
        "output": { "sentiment": "mixed", "score": 0.6 },
        "model": "claude-3-haiku",
        "status": "success",
        "duration_ms": 280
      }
    ]
  }'

# Response:
{ "accepted": true, "count": 2, "trace_ids": ["nw_x1y2z3...", "nw_a4b5c6..."] }

Mapped External Webhooks

A custom mapping receives arbitrary JSON at POST /api/v1/ingest/webhook/:mapping_id. Authenticate with the mapping-specific one-time key in X-Webhook-Key (or as a Bearer token), not with a project API key. The server pins organization and project ownership, applies the configured safe field transforms, redacts PII, enforces quota and deduplication, then uses the durable trace queue.

curl -X POST "https://api.observyze.com/api/v1/ingest/webhook/whm_xxxxx" \
  -H "X-Webhook-Key: ob_wh_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "request": "hello", "response": "world", "latency_ms": 125 }'

Mapping credentials are returned only at creation or regeneration time and are stored as bcrypt hashes. Legacy plaintext mapping credentials must be regenerated before use.

Simple Event — Field Reference

Error Handling

Observyze uses standard REST API error status codes. If a circuit breaker blocks a request, or credentials are invalid, we return explicit status details.

Programmatic Exception Catching

When using our SDK wrappers or calling the proxy, catch exceptions to safely handle circuit breaker blockades:

try {
  const response = await tracedOpenAI.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Execute query' }]
  });
} catch (error: any) {
  if (error.status === 429) {
    console.warn("Observyze Circuit Breaker is active! Serving fallback response.");
    // Fallback static prompt response logic here...
  } else {
    console.error("Standard SDK error caught:", error.message);
  }
}

Compliance Mode

Metadata-only mode is intended for strict data-governance environments. With proxy redirect disabled and content capture disabled, SDK-generated traces omit prompts, completions, arbitrary metadata, user/session identifiers, tags, and detailed errors before buffering. This is a technical privacy control—not a certification of GDPR, HIPAA, or SOC 2 compliance.

Configuration

Configure direct routing, content omission, and local redaction together:

import { ObservyzeClient } from '@observyze/sdk';
import OpenAI from 'openai';

const nw = new ObservyzeClient({
  apiKey: process.env.OBSERVYZE_API_KEY,

  // ── Compliance Mode ────────────────────────────────────────────────────────

  // 1. Bypass the proxy gateway: LLM traffic goes directly from YOUR server
  //    to OpenAI/Anthropic instead of the Observyze proxy.
  enableProxyRedirect: false,

  // 2. Omit customer content locally. Inputs, outputs, arbitrary metadata,
  //    user/session identifiers, tags, and detailed errors are never buffered.
  captureContent: false,

  // 3. Keep deterministic redaction enabled as defense in depth for the
  //    remaining allowlisted operational fields and imported history.
  //    The SDK scrubs emails, SSNs, credit cards, JWTs,
  //    API keys, phone numbers, IP addresses, and sensitive JSON keys from
  //    all trace spans BEFORE they are asynchronously uploaded as telemetry.
  enablePiiRedaction: true,
});

// Usage is identical — just wrap your client as normal.
const openai = nw.wrap(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));

// ✅ LLM call goes directly to OpenAI (not via Observyze proxy)
// ✅ Token counts, latency & cost metadata are still captured and uploaded
// ✅ Prompt and completion content are omitted locally before dispatch
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});

PII Categories Redacted

The following patterns are scrubbed from all trace input and output payloads — both client-side (SDK) and server-side (proxy gateway) as a defense-in-depth measure.

Security Controls and Boundaries

System Limitations

Observyze is designed with transparency. These are the known constraints and design boundaries of the current system.

Guides & Tutorials

Step-by-step developer tutorials for setting up intermediate and advanced configurations in Observyze.