Sessions API

Overview

Evaluation sessions group related evaluations into a single logical workflow. This is especially useful for multi-step processes like agent conversations, document review pipelines, or multi-turn chat interactions where policies need to consider the full context of what has happened so far.

As evaluations run within a session, Aguardic automatically tracks actions, data tags, tools used, and action counts. This accumulated context is available to the policy engine, enabling rules like "block if more than 5 tools have been called" or "warn if PII has been detected in this session."

Session Lifecycle

Sessions follow a simple lifecycle: ACTIVE to COMPLETED or TERMINATED.

• ACTIVE -- The session is open and accepting evaluations.
• COMPLETED -- The session ended normally.
• TERMINATED -- The session was ended early (e.g., due to a violation or timeout).

Authentication

All session endpoints require a per-integration API key in the Authorization header. See Authentication for details.

Create Session

Create a new evaluation session to group subsequent evaluations.

POST /v1/evaluation-sessions

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | entityId | string | No | UUID of a governed entity to link to this session. | | externalSessionId | string | No | Your system's session identifier for cross-referencing. Max 255 characters. | | expiresAt | string | No | ISO 8601 datetime for session expiration. After this time, evaluations cannot be added to the session. | | metadata | object | No | Arbitrary key-value data to associate with the session. |

Example

curl -X POST https://api.aguardic.com/v1/evaluation-sessions \
  -H "Authorization: Bearer ag_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSessionId": "conv-2024-01-15-abc",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "metadata": {
      "userId": "user-123",
      "channel": "web-chat"
    }
  }'

Response

{
  "success": true,
  "statusCode": 201,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "entityId": null,
    "externalSessionId": "conv-2024-01-15-abc",
    "startedAt": "2024-01-15T10:30:00.000Z",
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "metadata": {
      "userId": "user-123",
      "channel": "web-chat"
    }
  }
}

Use the returned id as the sessionId parameter in subsequent Evaluate requests.

Get Session

Retrieve a session with its full action chain and accumulated context.

GET /v1/evaluation-sessions/:sessionId

Example

curl https://api.aguardic.com/v1/evaluation-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ag_live_abc123def456"

Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "entityId": null,
    "entity": null,
    "integrationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "externalSessionId": "conv-2024-01-15-abc",
    "startedAt": "2024-01-15T10:30:00.000Z",
    "endedAt": null,
    "expiresAt": "2024-01-15T11:30:00.000Z",
    "metadata": {
      "userId": "user-123",
      "channel": "web-chat"
    },
    "actionCount": 3,
    "dataTags": ["pii", "financial"],
    "toolsUsed": ["send_email", "query_database"],
    "actions": [
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "sequence": 1,
        "action": "query_database",
        "toolName": "query_database",
        "dataTags": ["financial"],
        "outcome": "ALLOW",
        "evaluationRunId": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "metadata": {},
        "createdAt": "2024-01-15T10:31:00.000Z"
      },
      {
        "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
        "sequence": 2,
        "action": "send_email",
        "toolName": "send_email",
        "dataTags": ["pii"],
        "outcome": "WARN",
        "evaluationRunId": "f6a7b8c9-d0e1-2345-fabc-456789012345",
        "metadata": {},
        "createdAt": "2024-01-15T10:32:00.000Z"
      },
      {
        "id": "a7b8c9d0-e1f2-3456-abcd-567890123456",
        "sequence": 3,
        "action": "query_database",
        "toolName": "query_database",
        "dataTags": ["financial"],
        "outcome": "ALLOW",
        "evaluationRunId": "b8c9d0e1-f2a3-4567-bcde-678901234567",
        "metadata": {},
        "createdAt": "2024-01-15T10:33:00.000Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:33:00.000Z"
  }
}

Response Fields

| Field | Type | Description | |-------|------|-------------| | id | string | Unique session identifier. | | status | string | Current status: ACTIVE, COMPLETED, or TERMINATED. | | entityId | string \| null | Linked entity UUID, if any. | | entity | object \| null | Expanded entity object when an entity is linked. | | integrationId | string | The integration this session belongs to. | | externalSessionId | string \| null | Your system's session identifier. | | startedAt | string | ISO 8601 timestamp when the session started. | | endedAt | string \| null | ISO 8601 timestamp when the session ended. null while active. | | expiresAt | string \| null | ISO 8601 expiration timestamp. | | metadata | object | Custom metadata provided at creation. | | actionCount | number | Total number of evaluations run in this session. | | dataTags | string[] | Aggregated data tags across all actions (e.g., ["pii", "financial"]). | | toolsUsed | string[] | Aggregated tool names across all actions. | | actions | array | Ordered list of actions recorded during the session. |

Action Object

| Field | Type | Description | |-------|------|-------------| | id | string | Unique action identifier. | | sequence | number | 1-based position in the session's action chain. | | action | string | The action that was evaluated. | | toolName | string | Name of the tool or operation. | | dataTags | string[] | Data categories detected in this action. | | outcome | string | Evaluation result: ALLOW, WARN, or BLOCK. | | evaluationRunId | string | UUID of the evaluation run that produced this action. | | metadata | object | Additional metadata for this action. | | createdAt | string | ISO 8601 timestamp when this action was recorded. |

End Session

End an active session. Once ended, no further evaluations can be added.

POST /v1/evaluation-sessions/:sessionId/end

Request Body

| Field | Type | Required | Description | |-------|------|----------|-------------| | status | string | No | End status: COMPLETED or TERMINATED. Defaults to COMPLETED. |

Example

curl -X POST https://api.aguardic.com/v1/evaluation-sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/end \
  -H "Authorization: Bearer ag_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"status": "COMPLETED"}'

Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "COMPLETED",
    "endedAt": "2024-01-15T10:45:00.000Z",
    "actionCount": 5,
    "dataTags": ["pii", "financial"],
    "toolsUsed": ["send_email", "query_database"]
  }
}

Session Context in Policy Evaluation

When you include a sessionId in an Evaluate request, the policy engine receives the session's accumulated context:

• dataTags -- All data categories detected across previous actions in the session.
• toolsUsed -- All tools or operations invoked so far.
• actionCount -- How many evaluations have run in this session.
• recentActions -- The most recent actions for pattern detection.

This enables policies that reason about the full workflow, not just individual requests. For example:

• Block if the session has already triggered 3 warnings
• Require approval if PII was detected earlier in the session and the agent now wants to send an email
• Escalate severity when actionCount exceeds a threshold

Next Steps

• Evaluate API -- Send content for policy evaluation
• Evaluation Sessions Guide -- Patterns and best practices for sessions
• AI Systems -- Register AI systems and link integrations