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:
API Key: Used to create sessions and get JWT tokens
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
Success Response
Error 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:
Example Request
Error Response
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" } } ) 
