API Reference

AgentWatch exposes a REST API for budget enforcement, dashboard analytics, and account management. The base URL is https://api.agent-watch.dev.

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer aw_live_sk_xxx-xxx-proj-yyy

For BYOK (Bring Your Own Key) proxy requests, combine your AgentWatch token with your provider key:

Authorization: Bearer aw_live_sk_xxx:sk-proj-your-openai-key

Proxy Routes

Route LLM requests through AgentWatch for budget enforcement.

Method	Path	Description
POST	/v1/proxy/openai	Proxy to OpenAI
POST	/v1/proxy/anthropic	Proxy to Anthropic
POST	/v1/proxy/groq	Proxy to Groq
POST	/v1/proxy/gemini	Proxy to Google Gemini
POST	/v1/proxy/xai	Proxy to xAI (Grok)
POST	/v1/proxy/azure	Proxy to Azure OpenAI
POST	/v1/proxy/bedrock	Proxy to AWS Bedrock
POST	/v1/proxy/mistral	Proxy to Mistral
POST	/v1/proxy/cohere	Proxy to Cohere
POST	/v1/proxy/xiaomi	Proxy to Xiaomi

Budget Headers

Add these headers to enforce budget limits on proxy requests:

Header	Description	Example
X-AgentWatch-Session-Id	Unique session identifier	my-session-123
X-AgentWatch-Session-Budget-Usd	Per-session USD spending cap	2.00

Example (Python)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.agent-watch.dev/v1/proxy/openai",
    api_key="aw_live_sk_xxx:sk-proj-your-openai-key",
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "X-AgentWatch-Session-Budget-Usd": "2.00",
        "X-AgentWatch-Session-Id": "my-session",
    }
)

Example (TypeScript)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: "https://api.agent-watch.dev/v1/proxy/openai",
  apiKey: "aw_live_sk_xxx:sk-proj-your-openai-key",
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }],
}, {
  headers: {
    "X-AgentWatch-Session-Budget-Usd": "2.00",
    "X-AgentWatch-Session-Id": "my-session",
  }
});

Example (curl)

curl https://api.agent-watch.dev/v1/proxy/openai/chat/completions \
  -H "Authorization: Bearer aw_live_sk_xxx:sk-proj-your-openai-key" \
  -H "Content-Type: application/json" \
  -H "X-AgentWatch-Session-Budget-Usd: 2.00" \
  -H "X-AgentWatch-Session-Id: my-session" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Dashboard API

Analytics and management endpoints. All require authentication.

Method	Path	Description
GET	/v1/dashboard	Dashboard HTML
GET	/v1/dashboard/summary	Spend summary (total, requests, sessions, error rate)
GET	/v1/dashboard/spend-trend	Spend over time (daily/weekly)
GET	/v1/dashboard/sessions	Session cost breakdown
GET	/v1/dashboard/providers	Per-provider usage and latency
GET	/v1/dashboard/teams	Per-team spend breakdown
GET	/v1/dashboard/anomalies	Detected anomalies
GET	/v1/dashboard/analytics/advanced	Advanced analytics
GET	/v1/dashboard/agent-spend	Per-agent spend data
GET	/v1/dashboard/keys	API key management
POST	/v1/dashboard/keys	Generate new API key
DELETE	/v1/dashboard/keys	Revoke API key
GET	/v1/dashboard/settings	Account settings
POST	/v1/dashboard/settings	Update settings
GET	/v1/dashboard/audit_logs	Audit log entries
GET	/v1/dashboard/timeline	Governance timeline for a session

Authentication API

Method	Path	Description
POST	/v1/auth/signup	Create account (email + password)
POST	/v1/auth/login	Sign in
GET	/v1/auth/github	Initiate GitHub OAuth
GET	/v1/auth/github/callback	GitHub OAuth callback

Payments API

Method	Path	Description
GET	/v1/payments/public-key	Razorpay public key
POST	/v1/payments/create-order	Create payment order
POST	/v1/payments/verify	Verify payment
GET	/v1/promos/status	Check promo code status
POST	/v1/promos/validate	Validate promo code
POST	/v1/promos/redeem	Redeem promo code

Rules API

Custom governance rules (Pro/Enterprise only).

Method	Path	Description
GET	/v1/rules	List rules
POST	/v1/rules	Create rule
PUT	/v1/rules/:id	Update rule
DELETE	/v1/rules/:id	Delete rule

Error Responses

All errors return JSON:

{
  "error": {
    "message": "Missing or invalid AgentWatch bearer token.",
    "type": "agentwatch_proxy_error"
  }
}

Status	Meaning
400	Bad request (invalid input)
401	Authentication failed
402	Budget exceeded (session or team cap hit)
403	Forbidden (plan upgrade required)
404	Not found
429	Rate limited
500	Internal server error

OpenAPI Spec

The full OpenAPI 3.0 spec is available at openapi.yaml.