Documentation

Sessions API

REST API endpoints for creating and managing agent sessions.

Base URL

https://api.tryguardy.com

Create Session

namestringrequired

Descriptive name for the session.

agentNamestringrequired

Agent identifier for grouping.

userIdstringrequired

External user identifier.

metadataobject

Custom key-value data.

Request

POST /api/sdk/sessions

{
  "name": "Customer Support Request",
  "agentName": "support-agent",
  "userId": "user_123",
  "metadata": {
    "ticketId": "TKT-789",
    "channel": "web_chat"
  }
}

Response

{
  "id": "sess_abc123def456",
  "name": "Customer Support Request",
  "agentName": "support-agent",
  "userId": "user_123",
  "status": "active",
  "createdAt": "2025-01-12T10:30:00Z"
}

cURL Example

curl -X POST https://api.tryguardy.com/api/sdk/sessions \
  -H "Authorization: Bearer guardy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Request",
    "agentName": "support-agent",
    "userId": "user_123"
  }'

Update Session

statusstring

"completed" or "failed".

successboolean

Whether session completed successfully.

failureReasonstring

Reason for failure if success=false.

estimatedCostnumber

Total cost in USD.

durationMsnumber

Duration in milliseconds.

promptTokensnumber

Input tokens used.

completionTokensnumber

Output tokens used.

totalTokensnumber

Total tokens.

customMetricsobject

Custom numeric metrics.

Request

PATCH /api/sdk/sessions/:id

{
  "status": "completed",
  "success": true,
  "estimatedCost": 0.045,
  "durationMs": 3500,
  "promptTokens": 1500,
  "completionTokens": 500,
  "totalTokens": 2000,
  "customMetrics": {
    "satisfaction": 4.5,
    "resolution_time": 120
  }
}

Response

{
  "id": "sess_abc123def456",
  "name": "Customer Support Request",
  "status": "completed",
  "success": true,
  "estimatedCost": 0.045,
  "durationMs": 3500,
  "completedAt": "2025-01-12T10:30:03Z"
}

cURL Example

curl -X PATCH https://api.tryguardy.com/api/sdk/sessions/sess_abc123def456 \
  -H "Authorization: Bearer guardy_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "success": true,
    "estimatedCost": 0.045
  }'

Error Codes

Code	Title	Description
`400`	Bad Request	Missing required fields or invalid data
`401`	Unauthorized	Invalid or missing API key
`404`	Not Found	Session ID not found
`500`	Internal Server Error	Server error, please retry

Next Steps

Events API

Track events within sessions.

Python SDK

Use the SDK for easier integration.