REST API Reference

Complete documentation for the LLMGovernor REST API. Build custom integrations, dashboards, and analytics on top of your AI agent cost data.

Base URL

https://api.llmgovernor.ai/v1

Authentication

All API requests require authentication using your API key in the Authorization header:

curl -H "Authorization: Bearer llmgovernor_api_key_xxxxx" \\
     https://api.llmgovernor.ai/v1/events

Get your API key from the dashboard settings.

Rate Limits

Free tier: 100 requests/hour
Starter tier: 1,000 requests/hour
Growth tier: 10,000 requests/hour
Scale tier: Unlimited

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Events API

List Events

Get a list of cost tracking events.

Endpoint: GET /events

Parameters:

Parameter	Type	Description
`limit`	integer	Number of events to return (1-1000, default: 100)
`offset`	integer	Pagination offset (default: 0)
`start_date`	string	Filter events from this date (ISO 8601)
`end_date`	string	Filter events until this date (ISO 8601)
`agent_name`	string	Filter by agent name
`user_id`	string	Filter by user ID
`provider`	string	Filter by provider (openai, anthropic, etc.)
`tags`	object	Filter by tags (JSON object)

Example Request:

curl -H "Authorization: Bearer llmgovernor_api_key_xxxxx" \
     "https://api.blazeforagents.com/v1/events?limit=50&provider=openai"

Example Response:

{
  "events": [
    {
      "id": "evt_1234567890",
      "timestamp": "2024-01-15T10:30:00Z",
      "agent_name": "research_agent",
      "user_id": "user_123",
      "provider": "openai",
      "model": "gpt-4",
      "cost_usd": 0.045,
      "tokens_input": 150,
      "tokens_output": 75,
      "tags": {
        "department": "research",
        "project": "q1_analysis"
      },
      "metadata": {
        "request_id": "req_abc123",
        "duration_ms": 1250
      }
    }
  ],
  "pagination": {
    "total": 1234,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Get Event Details

Get details for a specific event.

Endpoint: GET /events/{event_id}

Example Request:

curl -H "Authorization: Bearer llmgovernor_api_key_xxxxx" \
     https://api.blazeforagents.com/v1/events/evt_1234567890

Example Response:

{
  "id": "evt_1234567890",
  "timestamp": "2024-01-15T10:30:00Z",
  "agent_name": "research_agent",
  "user_id": "user_123",
  "provider": "openai",
  "model": "gpt-4",
  "cost_usd": 0.045,
  "tokens_input": 150,
  "tokens_output": 75,
  "budget_remaining": 24.955,
  "tags": {
    "department": "research",
    "project": "q1_analysis"
  },
  "metadata": {
    "request_id": "req_abc123",
    "duration_ms": 1250,
    "prompt_tokens": 150,
    "completion_tokens": 75
  }
}

Analytics API

Cost Summary

Get aggregated cost data for analysis.

Endpoint: GET /analytics/costs

Parameters:

Parameter	Type	Description
`start_date`	string	Start date (ISO 8601, required)
`end_date`	string	End date (ISO 8601, required)
`group_by`	string	Group by: "day", "hour", "agent", "provider", "user"
`agent_name`	string	Filter by agent name
`user_id`	string	Filter by user ID
`provider`	string	Filter by provider
`tags`	object	Filter by tags

Example Request:

curl -H "Authorization: Bearer llmgovernor_api_key_xxxxx" \
     "https://api.blazeforagents.com/v1/analytics/costs?start_date=2024-01-01&end_date=2024-01-31&group_by=day"

Example Response:

{
  "summary": {
    "total_cost_usd": 156.78,
    "total_events": 3421,
    "total_tokens": 2834567,
    "average_cost_per_event": 0.0458
  },
  "data": [
    {
      "date": "2024-01-01",
      "cost_usd": 12.45,
      "events": 87,
      "tokens": 145632
    },
    {
      "date": "2024-01-02",
      "cost_usd": 18.92,
      "events": 134,
      "tokens": 234567
    }
  ]
}

Usage Metrics

Get detailed usage metrics and trends.

Endpoint: GET /analytics/usage

Example Response:

{
  "current_period": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "total_events": 3421,
    "unique_agents": 12,
    "unique_users": 45
  },
  "top_agents": [
    {
      "agent_name": "customer_support",
      "cost_usd": 45.67,
      "events": 892,
      "percentage": 29.1
    },
    {
      "agent_name": "research_assistant",
      "cost_usd": 38.23,
      "events": 567,
      "percentage": 24.4
    }
  ],
  "top_providers": [
    {
      "provider": "openai",
      "cost_usd": 98.45,
      "events": 2341,
      "percentage": 62.8
    },
    {
      "provider": "anthropic",
      "cost_usd": 58.33,
      "events": 1080,
      "percentage": 37.2
    }
  ]
}

Budgets API

List Budgets

Get all budget configurations.

Endpoint: GET /budgets

Example Response:

{
  "budgets": [
    {
      "id": "budget_123",
      "agent_name": "customer_support",
      "user_id": null,
      "amount_usd": 100.00,
      "period": "monthly",
      "spent_usd": 67.45,
      "remaining_usd": 32.55,
      "status": "active",
      "alert_threshold": 0.8,
      "tags": {
        "department": "support"
      },
      "created_at": "2024-01-01T00:00:00Z",
      "period_start": "2024-01-01T00:00:00Z",
      "period_end": "2024-01-31T23:59:59Z"
    }
  ]
}

Create Budget

Create a new budget rule.

Endpoint: POST /budgets

Request Body:

{
  "agent_name": "new_agent",
  "amount_usd": 50.00,
  "period": "monthly",
  "alert_threshold": 0.8,
  "enforcement": "block",
  "tags": {
    "department": "marketing"
  }
}

Update Budget

Update an existing budget.

Endpoint: PUT /budgets/{budget_id}

Request Body:

{
  "amount_usd": 75.00,
  "alert_threshold": 0.9
}

Delete Budget

Delete a budget rule.

Endpoint: DELETE /budgets/{budget_id}

Alerts API

List Alerts

Get alert configurations.

Endpoint: GET /alerts

Example Response:

{
  "alerts": [
    {
      "id": "alert_456",
      "name": "High Spend Alert",
      "trigger": "budget_threshold",
      "threshold": 0.8,
      "channels": ["email", "slack"],
      "active": true,
      "filters": {
        "agent_name": "expensive_agent"
      }
    }
  ]
}

Create Alert

Create a new alert rule.

Endpoint: POST /alerts

Request Body:

{
  "name": "Daily Spend Alert",
  "trigger": "daily_spend_limit",
  "threshold": 50.00,
  "channels": ["email"],
  "filters": {
    "tags": {
      "environment": "production"
    }
  }
}

Webhooks

Receive real-time notifications when events occur.

Configure Webhook

Endpoint: POST /webhooks

Request Body:

{
  "url": "https://your-app.com/llmgovernor-webhook",
  "events": ["cost_event", "budget_exceeded", "alert_triggered"],
  "secret": "your_webhook_secret"
}

Webhook Payload

Example webhook payload for a cost event:

{
  "event_type": "cost_event",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "event_id": "evt_1234567890",
    "agent_name": "research_agent",
    "cost_usd": 0.045,
    "budget_remaining": 24.955,
    "provider": "openai",
    "model": "gpt-4"
  }
}

Webhook Verification

Verify webhook authenticity using the signature header:

import hashlib
import hmac

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(f"sha256={expected}", signature)

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "BUDGET_EXCEEDED",
    "message": "Agent budget of $25.00 has been exceeded",
    "details": {
      "current_spend": 25.67,
      "budget_limit": 25.00,
      "agent_name": "research_agent"
    }
  }
}

Common Error Codes

Code	Description
`UNAUTHORIZED`	Invalid or missing API key
`FORBIDDEN`	Insufficient permissions
`NOT_FOUND`	Resource not found
`RATE_LIMITED`	Rate limit exceeded
`BUDGET_EXCEEDED`	Budget limit reached
`VALIDATION_ERROR`	Invalid request parameters

SDKs and Libraries

Official SDKs

Python: pip install llmgovernor
JavaScript/Node.js: npm install @llmgovernor/sdk
Go: go get github.com/llmgovernor/llmgovernor-go

Community Libraries

Ruby: llmgovernor-ruby
PHP: llmgovernor-php
Java: llmgovernor-java

Rate Limiting Best Practices

Implement exponential backoff for rate limit errors
Cache frequently accessed data to reduce API calls
Use webhooks instead of polling for real-time updates
Batch requests when possible

Example Integrations

Custom Dashboard

// Fetch cost data for dashboard
async function getDashboardData() {
  const response = await fetch('/api/llmgovernor/analytics/costs', {
    headers: {
      'Authorization': `Bearer ${process.env.LLMGOVERNOR_API_KEY}`,
    }
  });
  
  return response.json();
}

Slack Alert Bot

import requests

def send_slack_alert(budget_data):
    slack_webhook = "https://hooks.slack.com/your-webhook"
    
    message = {
        "text": f"🚨 Budget Alert: {budget_data['agent_name']} "
               f"has spent ${budget_data['spent']} of ${budget_data['limit']}"
    }
    
    requests.post(slack_webhook, json=message)

REST API Reference

Base URL

Authentication

Rate Limits

Events API

List Events

Get Event Details

Analytics API

Cost Summary

Usage Metrics

Budgets API

List Budgets

Create Budget

Update Budget

Delete Budget

Alerts API

List Alerts

Create Alert

Webhooks

Configure Webhook

Webhook Payload

Webhook Verification

Error Responses

Common Error Codes

SDKs and Libraries

Official SDKs

Community Libraries

Rate Limiting Best Practices

Example Integrations

Custom Dashboard

Slack Alert Bot

Support