Skip to content

Session Management API

Manage conversation sessions, update context variables mid-session, and confirm or cancel pending agent actions.

Close a Session

End a conversation session and stop billing.

POST /api/v1/sessions/{thread_id}/close

Request

curl -X POST https://api.ag2trust.com/api/v1/sessions/thread_abc123/close \
  -H "X-API-Key: cust_your_api_key"

response = requests.post(
    f"{BASE_URL}/api/v1/sessions/thread_abc123/close",
    headers={"X-API-Key": API_KEY}
)

Response (200 OK)

{
  "thread_id": "thread_abc123",
  "closed_at": "2025-01-15T10:45:00Z",
  "duration_seconds": 900,
  "billable": true
}
Field Type Description
thread_id string The closed session
closed_at string ISO 8601 close timestamp
duration_seconds integer Total session duration
billable boolean Whether this session counts toward billing

Update Session Variables

Update context variables for an active session. These variables persist for the remainder of the session.

PATCH /api/v1/sessions/{thread_id}

Request

curl -X PATCH https://api.ag2trust.com/api/v1/sessions/thread_abc123 \
  -H "X-API-Key: cust_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "context_variables": {
      "USER_PLAN": "enterprise",
      "ACCOUNT_STATUS": "active"
    }
  }'
Field Type Required Description
context_variables object Yes Key-value pairs. Keys must be UPPERCASE_SNAKE_CASE. Max 20 variables, 4KB total.

Response (200 OK)

{
  "thread_id": "thread_abc123",
  "variables_updated": 2,
  "total_variables": 5
}

Confirm or Cancel a Pending Action

When an agent proposes an action that requires user confirmation (e.g., sending an email), the pool endpoint response includes a pending_action field. Use this endpoint to confirm or cancel it.

POST /api/v1/sessions/{thread_id}/actions/{action_id}

Request

curl -X POST https://api.ag2trust.com/api/v1/sessions/thread_abc123/actions/act_xyz789 \
  -H "X-API-Key: cust_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"confirmed": true}'
Field Type Required Description
confirmed boolean Yes true to execute the action, false to cancel

Response — Cancel (200 OK, synchronous)

{
  "thread_id": "thread_abc123",
  "action_id": "act_xyz789",
  "status": "cancelled",
  "message": "Action cancelled"
}

Response — Confirm (202 Accepted, asynchronous)

{
  "thread_id": "thread_abc123",
  "action_id": "act_xyz789",
  "callback_id": "cb_abc123",
  "status": "processing",
  "message": "Action confirmed, executing..."
}

When confirmed, the action is executed asynchronously. The next call to the pool endpoint with the same thread_id will include the action result.

Pending Action Flow

1. Send message → Pool endpoint returns pending_action
                    {
                      "action_id": "act_xyz789",
                      "tool": "send_email",
                      "preview": {
                        "to": "user@example.com",
                        "subject": "Order Confirmation",
                        "body": "Your order #123 has been confirmed..."
                      },
                      "expires_at": "2025-01-15T10:35:00Z"
                    }

2. Show preview to user → User decides

3a. Confirm → POST /sessions/{thread_id}/actions/{action_id} {"confirmed": true}
    → 202 Accepted, action executes

3b. Cancel → POST /sessions/{thread_id}/actions/{action_id} {"confirmed": false}
    → 200 OK, action cancelled

Action Expiration

Pending actions have an expires_at timestamp. Actions that are not confirmed or cancelled before expiration are automatically cancelled.

API Reference

Method Endpoint Description
POST /api/v1/sessions/{thread_id}/close Close session
PATCH /api/v1/sessions/{thread_id} Update session variables
POST /api/v1/sessions/{thread_id}/actions/{action_id} Confirm/cancel pending action

Next Steps