Documentation Index Fetch the complete documentation index at: https://docs.agentops.ai/llms.txt
Use this file to discover all available pages before exploring further.
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" } } )
