Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix REST API documentation #591

Closed
wants to merge 12 commits into from
Closed

Fix REST API documentation #591

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
21d6991
Add REST API test script
devin-ai-integration[bot] Dec 18, 2024
d2ba473
Update test script to match SDK implementation
devin-ai-integration[bot] Dec 18, 2024
217fae9
test: add requests_mock for REST API testing
devin-ai-integration[bot] Dec 18, 2024
2aeaa60
docs: update REST API documentation to match SDK implementation
devin-ai-integration[bot] Dec 18, 2024
f1b1bc1
ci: retry pre-commit checks due to GitHub 503 error
devin-ai-integration[bot] Dec 18, 2024
89220ed
style: fix code formatting in test_rest_api.py
devin-ai-integration[bot] Dec 18, 2024
451f362
style: consolidate headers dict and fix trailing comma
devin-ai-integration[bot] Dec 18, 2024
12d336c
style: apply ruff-format suggestions
devin-ai-integration[bot] Dec 18, 2024
b708200
style: add blank line before main block per ruff-format
devin-ai-integration[bot] Dec 18, 2024
ad98c3b
docs: add required id field to event payloads and update test examples
devin-ai-integration[bot] Dec 19, 2024
3761f46
style: fix JSON formatting in test_rest_api.py per ruff-format
devin-ai-integration[bot] Dec 19, 2024
47eae15
ci: trigger fresh build
devin-ai-integration[bot] Dec 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
186 changes: 146 additions & 40 deletions docs/v1/integrations/rest.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,30 +22,46 @@ When you create a session, you'll use your API key and receive a JWT token in re

<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/create_session \
-H "Content-Type: application/json" \
curl -X POST https://api.agentops.ai/v2/create_session \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "X-Agentops-Api-Key: your_api_key" \
-d '{
"id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z"
"session": {
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z",
"tags": ["production"],
"host_env": {
"OS": {
"OS": "Windows",
"OS Release": "11"
}
}
}
}'
```

```json Success Response
```json Success Response (200 OK)
{
"status": "success",
"jwt": "eyJhbGciOiJIUzI1NiIs...",
"session_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

```bash Error Response
HTTP/1.1 401 Unauthorized
```json Error Response (401 Unauthorized)
{
"error": "Invalid API key",
"message": "Please check your API key and try again"
}
```

```json Error Response (400 Bad Request)
{
"error": "Invalid request",
"message": "Missing required fields or invalid format"
}
```
</CodeGroup>

### Using JWT Tokens
Expand All @@ -54,22 +70,42 @@ Use the JWT token in the Authorization header for all subsequent requests:

<CodeGroup>
```bash Example Request
curl -X POST https://api.agentops.ai/create_events \
curl -X POST https://api.agentops.ai/v2/create_events \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-d '{
"events": [{
"type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z"
"event_type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z",
"end_timestamp": "2024-03-14T12:01:02Z",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"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
}]
}'
```

```bash Error Response
HTTP/1.1 401 Unauthorized
```json Error Response (401 Unauthorized)
{
"error": "Invalid or expired JWT",
"message": "Please reauthorize using /reauthorize_jwt"
"message": "Please reauthorize using /v2/reauthorize_jwt"
}
```

```json Error Response (429 Too Many Requests)
{
"error": "Rate limit exceeded",
"message": "Please try again later"
}
```
</CodeGroup>
Expand All @@ -81,21 +117,43 @@ JWTs expire after 24 hours. When a token expires, use your API key to get a new
<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/v2/reauthorize_jwt \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "X-Agentops-Api-Key: your_api_key" \
-d '{
"session_id": "550e8400-e29b-41d4-a716-446655440000"
}'
```

```json Success Response
```json Success Response (200 OK)
{
"status": "success",
"jwt": "eyJhbGciOiJIUzI1NiIs..."
}
```

```json Error Response (401 Unauthorized)
{
"error": "Invalid API key",
"message": "Please check your API key and try again"
}
```
</CodeGroup>

## Error Handling

The API uses standard HTTP status codes:

| Status Code | Description |
|------------|-------------|
| 200 | Success |
| 400 | Invalid Request - Check request format and required fields |
| 401 | Unauthorized - Invalid or missing API key/JWT |
| 408 | Request Timeout |
| 413 | Payload Too Large |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |

## 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:
Expand All @@ -115,11 +173,12 @@ Start a new monitoring session using your generated session ID:
<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/v2/create_session \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "X-Agentops-Api-Key: your_api_key" \
-d '{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z",
"tags": ["production", "customer-service"],
"host_env": {
Expand Down Expand Up @@ -155,7 +214,7 @@ X-Agentops-Api-Key: your_api_key

{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"init_timestamp": "2024-03-14T12:00:00Z",
"tags": ["production", "customer-service"],
"host_env": {
Expand Down Expand Up @@ -192,11 +251,12 @@ Update an existing session (e.g., when it ends):
<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/v2/update_session \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "Authorization: Bearer your_jwt_token" \
-d '{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"end_timestamp": "2024-03-14T12:05:00Z",
"end_state": "Success",
"end_state_reason": "Task successfully completed",
Comment on lines 251 to 262
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential Issue:

Ensure Backward Compatibility for API Payload Change
The change from 'id' to 'session_id' in the API payload is a significant modification that can disrupt existing integrations. This change should be clearly documented and communicated to all API users to prevent unexpected failures.

Actionable Steps:

  • Documentation: Update the API documentation to reflect this change and highlight it as a breaking change.
  • Communication: Notify all users through appropriate channels (e.g., email, developer portal) about the change and its implications.
  • Backward Compatibility: Consider implementing a temporary backward compatibility layer that accepts both 'id' and 'session_id' to give users time to transition.
  • Migration Guide: Provide a detailed migration guide to assist users in updating their integrations.

These steps will help mitigate the impact of this change and ensure a smoother transition for users. 📢

Comment on lines 251 to 262
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential Issue:

Potential Breaking Change in JSON Structure
The change from 'id' to 'session_id' in the JSON structure is a significant modification that could lead to compatibility issues. This change might break existing functionality if other parts of the codebase or external systems rely on the original 'id' field.

Actionable Steps:

  • Review Dependencies: Thoroughly review all parts of the codebase and any external systems that interact with this JSON structure to ensure they are updated to use 'session_id' instead of 'id'.
  • Backward Compatibility: Consider implementing a backward compatibility layer or a migration path to handle systems that still expect the 'id' field.
  • Testing: Conduct comprehensive testing to ensure that the change does not introduce any regressions or unexpected behavior.
  • Documentation: Update any relevant documentation to reflect this change, ensuring that all stakeholders are aware of the new structure.

By following these steps, you can mitigate the risk of breaking existing functionality and ensure a smooth transition to the new JSON structure. 🚀

Expand All @@ -212,7 +272,7 @@ Authorization: Bearer your_jwt_token

{
"session": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"end_timestamp": "2024-03-14T12:05:00Z",
"end_state": "Success",
"end_state_reason": "Task successfully completed",
Expand All @@ -231,14 +291,16 @@ Track LLM calls, tool usage, or other events:
<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/v2/create_events \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "Authorization: Bearer your_jwt_token" \
-d '{
"events": [
{
"type": "llm",
"event_type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z",
"end_timestamp": "2024-03-14T12:01:02Z",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"model": "gpt-4",
"prompt": [
{"role": "system", "content": "You are a helpful assistant"},
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential Issue:

Potential Breaking Change in JSON Payload Key
The change from 'type' to 'event_type' in the JSON payload is a significant modification that could lead to breaking changes if the receiving API is not updated to handle the new key. This could result in failures in data processing or rejection of requests.

Actionable Steps:

  • Verify API Compatibility: Confirm with the API documentation or the API development team that the change from 'type' to 'event_type' is intentional and supported.
  • System Update: Ensure that all parts of the system interacting with this API are updated to use 'event_type' instead of 'type'.
  • Testing: Conduct thorough testing to ensure that the change does not introduce any regressions or failures in the system.

This change is critical and should be handled with caution to avoid disruptions in service.

Expand All @@ -252,7 +314,7 @@ curl -X POST https://api.agentops.ai/v2/create_events \
"completion_tokens": 80
},
{
"type": "tool",
"event_type": "tool",
"name": "database_query",
"init_timestamp": "2024-03-14T12:01:03Z",
"end_timestamp": "2024-03-14T12:01:04Z",
Expand All @@ -271,9 +333,10 @@ Authorization: Bearer your_jwt_token
{
"events": [
{
"type": "llm",
"event_type": "llm",
"init_timestamp": "2024-03-14T12:01:00Z",
"end_timestamp": "2024-03-14T12:01:02Z",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"model": "gpt-4",
"prompt": [
{"role": "system", "content": "You are a helpful assistant"},
Expand All @@ -287,7 +350,7 @@ Authorization: Bearer your_jwt_token
"completion_tokens": 80
},
{
"type": "tool",
"event_type": "tool",
"name": "database_query",
"init_timestamp": "2024-03-14T12:01:03Z",
"end_timestamp": "2024-03-14T12:01:04Z",
Expand All @@ -306,7 +369,8 @@ Update existing events (e.g., adding completion information):
<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/v2/update_events \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "Authorization: Bearer your_jwt_token" \
-d '{
"events": [
Expand Down Expand Up @@ -347,7 +411,8 @@ Register a new agent in a session:
<CodeGroup>
```bash curl
curl -X POST https://api.agentops.ai/v2/create_agent \
-H "Content-Type: application/json" \
-H "Content-Type: application/json; charset=UTF-8" \
-H "Accept: */*" \
-H "Authorization: Bearer your_jwt_token" \
-d '{
"id": "agent-123",
Expand Down Expand Up @@ -376,34 +441,68 @@ Here's a complete example using Python's requests library:
import requests
import uuid
from datetime import datetime, timezone
import json

# Configuration
API_KEY = "your_api_key"
BASE_URL = "https://api.agentops.ai"
HEADERS = {
"Content-Type": "application/json; charset=UTF-8",
"Accept": "*/*"
}

def handle_response(response):
"""Handle API response and common errors"""
try:
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
if response.status_code == 401:
print("Authentication error. Check your API key or JWT token.")
elif response.status_code == 429:
print("Rate limit exceeded. Please try again later.")
elif response.status_code == 400:
print("Invalid request format:", response.json().get("message"))
else:
print(f"HTTP error occurred: {e}")
return None
except Exception as e:
print(f"An error occurred: {e}")
return None

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

session_data = handle_response(session_response)
if not session_data:
print("Failed to create session")
exit(1)

jwt_token = session_data["jwt"]

# Track LLM call
requests.post(
event_headers = {**HEADERS, "Authorization": f"Bearer {jwt_token}"}
event_response = requests.post(
f"{BASE_URL}/v2/create_events",
headers={"Authorization": f"Bearer {jwt_token}"},
headers=event_headers,
json={
"events": [{
"type": "llm",
"event_type": "llm",
"init_timestamp": datetime.now(timezone.utc).isoformat(),
"end_timestamp": datetime.now(timezone.utc).isoformat(),
"session_id": session_id,
"model": "gpt-4",
"prompt": "Hello, world!",
"completion": "Hi there!",
Expand All @@ -413,17 +512,24 @@ requests.post(
}
)

if not handle_response(event_response):
print("Failed to create event")
exit(1)

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

if not handle_response(end_response):
print("Failed to end session")
```
</CodeGroup>
Loading
Loading