Agent Session API

The Agent Session API provides endpoints for managing AI agent audit sessions, querying session event timelines, recalculating risk scores, and configuring per-agent tool authorization policies. Use these endpoints to integrate agent session auditing into your orchestration framework.

For the admin guide covering concepts, risk scoring, and configuration, see Agent Session Auditing Admin Guide.

---

Authentication

All endpoints require authentication via Bearer token with admin role:

Authorization: Bearer <admin-api-key>

---

Sessions

Base path: /api/v1/admin/agent-sessions

Create a session

Method	Path	Auth	Description
POST	/api/v1/admin/agent-sessions	Bearer (admin)	Create a new agent audit session

Request body:

Field	Type	Required	Description
name	string	No	Human-readable session name (max 255 chars)
agent_identity_id	UUID	No	Reference to a registered agent identity
agent_identity	string	No	Agent identity label (max 255 chars)

Example:

curl -X POST https://your-platform/api/v1/admin/agent-sessions \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quarterly-report-generation",
    "agent_identity": "research-assistant",
    "agent_identity_id": "019577a3-1111-2222-3333-444455556666"
  }'

Response (201 Created):

{
  "id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "019577a3-0000-0000-0000-000000000001",
  "agent_identity_id": "019577a3-1111-2222-3333-444455556666",
  "agent_identity": "research-assistant",
  "name": "quarterly-report-generation",
  "status": "active",
  "session_risk_score": 0.0,
  "event_count": 0,
  "risk_signals": null,
  "created_at": "2026-04-01T10:00:00Z",
  "completed_at": null
}

---

List sessions

Method	Path	Auth	Description
GET	/api/v1/admin/agent-sessions	Bearer (admin)	List sessions with pagination and filters

Query parameters:

Parameter	Type	Default	Description
offset	integer	0	Number of items to skip
limit	integer	50	Results per page (max 500)
status	string	—	Filter by status: active, completed, terminated
user_id	UUID	—	Filter by the user who created the session
agent_identity	string	—	Filter by agent identity label (exact match)
date_from	datetime	—	Only sessions created at or after this ISO 8601 timestamp
date_to	datetime	—	Only sessions created at or before this ISO 8601 timestamp

Example:

curl "https://your-platform/api/v1/admin/agent-sessions?status=active&agent_identity=research-assistant&limit=20" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK):

{
  "items": [
    {
      "id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "019577a3-0000-0000-0000-000000000001",
      "agent_identity_id": "019577a3-1111-2222-3333-444455556666",
      "agent_identity": "research-assistant",
      "name": "quarterly-report-generation",
      "status": "active",
      "session_risk_score": 52.0,
      "event_count": 12,
      "risk_signals": null,
      "created_at": "2026-04-01T10:00:00Z",
      "completed_at": null
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

---

Get session detail

Method	Path	Auth	Description
GET	/api/v1/admin/agent-sessions/{session_id}	Bearer (admin)	Get session detail with inline event timeline

Returns the full session object plus an events array containing the audit event timeline (paginated via query parameters).

Query parameters:

Parameter	Type	Default	Description
events_limit	integer	200	Maximum events to return (max 1000)
events_offset	integer	0	Number of events to skip

Example:

curl "https://your-platform/api/v1/admin/agent-sessions/019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b?events_limit=50" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK):

{
  "id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "019577a3-0000-0000-0000-000000000001",
  "agent_identity_id": "019577a3-1111-2222-3333-444455556666",
  "agent_identity": "research-assistant",
  "name": "quarterly-report-generation",
  "status": "completed",
  "session_risk_score": 32.0,
  "event_count": 4,
  "risk_signals": {
    "breadth": 40,
    "violation_rate": 28,
    "speed_anomaly": 10,
    "novelty": 45
  },
  "created_at": "2026-04-01T10:00:00Z",
  "completed_at": "2026-04-01T10:05:30Z",
  "events": [
    {
      "id": "019577a3-aaaa-bbbb-cccc-ddddeeee0001",
      "action": "mcp.security_eval",
      "model_id": "gpt-4o",
      "provider": "openai",
      "token_count_input": 150,
      "token_count_output": 320,
      "cost_estimate": 0.0023,
      "latency_ms": 245,
      "metadata": {
        "server_name": "knowledge-base",
        "tool_name": "search",
        "decision": "allow"
      },
      "created_at": "2026-04-01T10:00:02Z"
    }
  ]
}

---

Update / end a session

Method	Path	Auth	Description
PATCH	/api/v1/admin/agent-sessions/{session_id}	Bearer (admin)	Update session name or status

Request body:

Field	Type	Required	Description
status	string	No	New status: active, completed, or terminated
name	string	No	Updated session name (max 255 chars)

When status is set to completed or terminated, the completed_at timestamp is automatically set to the current time.

Example — end a session:

curl -X PATCH https://your-platform/api/v1/admin/agent-sessions/019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "name": "quarterly-report-generation (done)"
  }'

Response (200 OK):

{
  "id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "019577a3-0000-0000-0000-000000000001",
  "agent_identity_id": "019577a3-1111-2222-3333-444455556666",
  "agent_identity": "research-assistant",
  "name": "quarterly-report-generation (done)",
  "status": "completed",
  "session_risk_score": 32.0,
  "event_count": 4,
  "risk_signals": null,
  "created_at": "2026-04-01T10:00:00Z",
  "completed_at": "2026-04-01T10:05:30Z"
}

Note

Once a session is marked completed or terminated, it cannot be reopened. Start a new session for additional work.

---

Get session timeline

Method	Path	Auth	Description
GET	/api/v1/admin/agent-sessions/{session_id}/timeline	Bearer (admin)	Get the ordered audit event timeline for a session

Returns a flat array of AuditEventSummary objects ordered by created_at ascending.

Query parameters:

Parameter	Type	Default	Description
limit	integer	200	Maximum events to return (max 1000)
offset	integer	0	Number of events to skip

Example:

curl "https://your-platform/api/v1/admin/agent-sessions/019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b/timeline?limit=100" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK):

[
  {
    "id": "019577a3-aaaa-bbbb-cccc-ddddeeee0001",
    "action": "mcp.security_eval",
    "model_id": "gpt-4o",
    "provider": "openai",
    "token_count_input": 150,
    "token_count_output": 320,
    "cost_estimate": 0.0023,
    "latency_ms": 245,
    "metadata": {
      "server_name": "knowledge-base",
      "tool_name": "search",
      "decision": "allow"
    },
    "created_at": "2026-04-01T10:00:02Z"
  },
  {
    "id": "019577a3-aaaa-bbbb-cccc-ddddeeee0002",
    "action": "agent.tool_call.denied",
    "model_id": null,
    "provider": null,
    "token_count_input": null,
    "token_count_output": null,
    "cost_estimate": null,
    "latency_ms": 2,
    "metadata": {
      "server_name": "salesforce",
      "tool_name": "update_account",
      "reason": "Tool not in agent allowlist"
    },
    "created_at": "2026-04-01T10:00:08Z"
  }
]

Event fields:

Field	Type	Description
id	UUID	Audit event ID
action	string	Event type (e.g., mcp.security_eval, agent.tool_call.denied, agent.session.risk_alert)
model_id	string or null	AI model used, if applicable
provider	string or null	AI provider name, if applicable
token_count_input	integer or null	Input token count
token_count_output	integer or null	Output token count
cost_estimate	float or null	Estimated cost in USD
latency_ms	integer or null	Processing latency in milliseconds
metadata	object or null	Additional event-specific data
created_at	datetime	When the event occurred

---

Recalculate session risk score

Method	Path	Auth	Description
POST	/api/v1/admin/agent-sessions/{session_id}/risk-score	Bearer (admin)	Recalculate and persist risk score for a session

Triggers risk scoring heuristics against all events in the session. If the recalculated score exceeds the alert threshold (hardcoded at 75.0 in the current release — org-level tuning is on the roadmap, see Agent session auditing), an agent.session.risk_alert audit event is emitted.

Example:

curl -X POST https://your-platform/api/v1/admin/agent-sessions/019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b/risk-score \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK): Returns the updated session object with the new session_risk_score and risk_signals.

{
  "id": "019577a3-7c4e-7def-8a1b-3c5d7e9f1a2b",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "019577a3-0000-0000-0000-000000000001",
  "agent_identity_id": "019577a3-1111-2222-3333-444455556666",
  "agent_identity": "research-assistant",
  "name": "quarterly-report-generation",
  "status": "active",
  "session_risk_score": 78.5,
  "event_count": 15,
  "risk_signals": {
    "breadth": 85,
    "violation_rate": 60,
    "speed_anomaly": 72,
    "novelty": 90
  },
  "created_at": "2026-04-01T10:00:00Z",
  "completed_at": null
}

---

Agent tool authorization policies

Base path: /api/agent/policies

Per-agent-identity tool authorization policies control which MCP tools specific agents can call.

Create a policy

Method	Path	Auth	Description
POST	/api/agent/policies	Bearer (admin)	Create a new agent tool authorization policy

Request body:

Field	Type	Required	Description
agent_identity	string	Yes	Agent identity label (max 255 chars)
mcp_server_id	UUID	No	Scope to a specific MCP server (null = all servers)
tool_pattern	string	Yes	Tool name or glob pattern (max 255 chars, e.g., search, salesforce:*)
action	string	No	allow (default) or deny

Example:

curl -X POST https://your-platform/api/agent/policies \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_identity": "data-analyst",
    "mcp_server_id": "019577b2-1111-2222-3333-444455556666",
    "tool_pattern": "query",
    "action": "allow"
  }'

Response (201 Created):

{
  "id": "019577b2-4a3c-7890-bc12-de34f5678901",
  "org_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent_identity": "data-analyst",
  "mcp_server_id": "019577b2-1111-2222-3333-444455556666",
  "tool_pattern": "query",
  "action": "allow",
  "created_at": "2026-04-01T10:30:00Z"
}

---

List policies

Method	Path	Auth	Description
GET	/api/agent/policies	Bearer (admin)	List all agent tool authorization policies

Query parameters:

Parameter	Type	Default	Description
offset	integer	0	Number of items to skip
limit	integer	50	Results per page (max 500)
agent_identity	string	—	Filter by agent identity label (exact match)
mcp_server_id	UUID	—	Filter by MCP server ID

Example:

curl "https://your-platform/api/agent/policies?agent_identity=data-analyst&limit=10" \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (200 OK):

{
  "items": [
    {
      "id": "019577b2-4a3c-7890-bc12-de34f5678901",
      "org_id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_identity": "data-analyst",
      "mcp_server_id": "019577b2-1111-2222-3333-444455556666",
      "tool_pattern": "query",
      "action": "allow",
      "created_at": "2026-04-01T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

---

Get a policy

Method	Path	Auth	Description
GET	/api/agent/policies/{policy_id}	Bearer (admin)	Get a single agent tool authorization policy

Example:

curl https://your-platform/api/agent/policies/019577b2-4a3c-7890-bc12-de34f5678901 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Returns the same schema as the create response.

---

Update a policy

Method	Path	Auth	Description
PUT	/api/agent/policies/{policy_id}	Bearer (admin)	Update an agent tool authorization policy

Request body: Only tool_pattern and action can be updated.

Field	Type	Required	Description
tool_pattern	string	No	Updated tool name or glob pattern
action	string	No	allow or deny

Example:

curl -X PUT https://your-platform/api/agent/policies/019577b2-4a3c-7890-bc12-de34f5678901 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "deny"
  }'

Response (200 OK): Returns the updated policy object.

---

Delete a policy

Method	Path	Auth	Description
DELETE	/api/agent/policies/{policy_id}	Bearer (admin)	Delete an agent tool authorization policy

Example:

curl -X DELETE https://your-platform/api/agent/policies/019577b2-4a3c-7890-bc12-de34f5678901 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response (204 No Content)

Caution

Deleting a policy does not end active sessions for that agent. Active sessions continue with no tool authorization restrictions (all tools allowed). Create a replacement policy before deleting the old one if you need continuous enforcement.

---

Error codes

Status	Code	Description
400	invalid_request	Missing required fields or invalid field values
401	unauthorized	Missing or invalid API key
403	forbidden	API key lacks admin role
404	not_found	Session or policy ID does not exist
409	conflict	Duplicate policy (same agent_identity, server, and tool_pattern)
422	invalid_tool_pattern	Tool pattern format is invalid
429	rate_limited	Too many requests. Retry after the Retry-After header value.

Error response format:

{
  "error": {
    "code": "not_found",
    "message": "Agent audit session not found."
  }
}