The AgentOps REST API allows you to integrate agent monitoring directly into your application without using our Python SDK. This is useful for:

  • Non-Python applications
  • Custom integrations
  • Direct API access

For a complete API reference, you can view our OpenAPI specification.

​
Authentication

The AgentOps API uses a two-step authentication process:

  1. API Key: Used to create sessions and get JWT tokens
  2. JWT: Used for all operations within a session

​
Initial Authentication

When you create a session, you’ll use your API key and receive a JWT token in response:

curl -X POST https://api.agentops.ai/create_session \
  -H "Content-Type: application/json" \
  -H "X-Agentops-Api-Key: your_api_key" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "init_timestamp": "2024-03-14T12:00:00Z"
  }'

​
Using JWT Tokens

Use the JWT token in the Authorization header for all subsequent requests:

curl -X POST https://api.agentops.ai/create_events \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "llm",
      "init_timestamp": "2024-03-14T12:01:00Z"
    }]
  }'

​
Refreshing Tokens

JWTs expire after 24 hours. When a token expires, use your API key to get a new one:

curl -X POST https://api.agentops.ai/v2/reauthorize_jwt \
  -H "Content-Type: application/json" \
  -H "X-Agentops-Api-Key: your_api_key" \
  -d '{
    "session_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

​
Session Management

Sessions require a unique identifier that you generate client-side. While any unique string will work, we recommend using UUIDs for consistency. Here’s how to generate one in Python:

import uuid
session_id = str(uuid.uuid4())
# "550e8400-e29b-41d4-a716-446655440000"

​
Create Session

Start a new monitoring session using your generated session ID:

curl -X POST https://api.agentops.ai/v2/create_session \
  -H "Content-Type: application/json" \
  -H "X-Agentops-Api-Key: your_api_key" \
  -d '{
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "init_timestamp": "2024-03-14T12:00:00Z",
      "tags": ["production", "customer-service"],
      "host_env": {
        "OS": {
          "OS": "Windows",
          "OS Release": "11",
          "OS Version": "10.0.22631"
        },
        "CPU": {
          "CPU Usage": "5.9%",
          "Total cores": 12
        },
        "RAM": {
          "Used": "14.49 GB",
          "Total": "31.75 GB"
        },
        "SDK": {
          "Python Version": "3.12.0",
          "System Packages": {
            "agentops": "0.3.17",
            "openai": "1.2.3"
          }
        }
      }
    }
  }'

​
Update Session

Update an existing session (e.g., when it ends):

curl -X POST https://api.agentops.ai/v2/update_session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "end_timestamp": "2024-03-14T12:05:00Z",
      "end_state": "Success",
      "end_state_reason": "Task successfully completed",
      "tags": ["production", "updated-tag"]
    }
  }'

​
Event Tracking

​
Create Events

Track LLM calls, tool usage, or other events:

curl -X POST https://api.agentops.ai/v2/create_events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "events": [
      {
        "type": "llm",
        "init_timestamp": "2024-03-14T12:01:00Z",
        "end_timestamp": "2024-03-14T12:01:02Z",
        "model": "gpt-4",
        "prompt": [
          {"role": "system", "content": "You are a helpful assistant"},
          {"role": "user", "content": "Analyze this data..."}
        ],
        "completion": {
          "role": "assistant",
          "content": "Based on the data..."
        },
        "prompt_tokens": 150,
        "completion_tokens": 80
      },
      {
        "type": "tool",
        "name": "database_query",
        "init_timestamp": "2024-03-14T12:01:03Z",
        "end_timestamp": "2024-03-14T12:01:04Z",
        "input": "SELECT * FROM users",
        "output": "Retrieved 5 users"
      }
    ]
  }'

​
Update Events

Update existing events (e.g., adding completion information):

curl -X POST https://api.agentops.ai/v2/update_events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "events": [
      {
        "event_id": "event-id-123",
        "end_timestamp": "2024-03-14T12:01:02Z",
        "completion": "Updated completion text",
        "completion_tokens": 100
      }
    ]
  }'

​
Agent Management

​
Create Agent

Register a new agent in a session:

curl -X POST https://api.agentops.ai/v2/create_agent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_jwt_token" \
  -d '{
    "id": "agent-123",
    "name": "Research Assistant"
  }'

​
Example Integration

Here’s a complete example using Python’s requests library:

import requests
import uuid
from datetime import datetime, timezone

# Configuration
API_KEY = "your_api_key"
BASE_URL = "https://api.agentops.ai"

# Create session
session_id = str(uuid.uuid4())
response = requests.post(
    f"{BASE_URL}/v2/create_session",
    headers={"X-Agentops-Api-Key": API_KEY},
    json={
        "session": {
            "id": session_id,
            "init_timestamp": datetime.now(timezone.utc).isoformat(),
            "tags": ["example"]
        }
    }
)
jwt_token = response.json()["jwt"]

# Track LLM call
requests.post(
    f"{BASE_URL}/v2/create_events",
    headers={"Authorization": f"Bearer {jwt_token}"},
    json={
        "events": [{
            "type": "llm",
            "init_timestamp": datetime.now(timezone.utc).isoformat(),
            "model": "gpt-4",
            "prompt": "Hello, world!",
            "completion": "Hi there!",
            "prompt_tokens": 3,
            "completion_tokens": 2
        }]
    }
)

# End session
requests.post(
    f"{BASE_URL}/v2/update_session",
    headers={"Authorization": f"Bearer {jwt_token}"},
    json={
        "session": {
            "id": session_id,
            "end_timestamp": datetime.now(timezone.utc).isoformat(),
            "end_state": "completed"
        }
    }
)