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

Our Node/TypeScript and Python SDKs provide deeper tracing capabilities. They intercept requests locally, support advanced tracing of non-LLM steps (like databases, vector retrievals, or code calculations), and safely shard credentials in memory.

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 route Google Gemini requests either using direct HTTP post requests or the standard SDK using a custom fetch handler:

import { GoogleGenerativeAI } from '@google/generative-ai';

// Instantiate Gemini SDK, routing requests dynamically through the proxy gateway
const genAI = new GoogleGenerativeAI(process.env.OBSERVYZE_KEY);
const model = genAI.getGenerativeModel({
  model: 'gemini-pro',
  // Optional custom fetch routing for Gemini
});

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 or wrap events in an { events: [...] } object to send up to 100 events per request. Ideal for flushing buffered logs at regular intervals.

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..."] }

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

Guides & Tutorials

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