Sessions

A session groups related guard calls so output evaluation can use prior input context and so risk can accumulate across turns.

session_id lifecycle

When you call POST /v1/guard/input, you may pass session_id or omit it. If omitted, the server generates an id (prefix def- plus a short random suffix). The response always includes the effective session_id.

You should reuse that value for subsequent input turns in the same conversation and for POST /v1/guard/output after the model responds. Treat session_id as an opaque correlation identifier, not a capability secret.

TTL

guards.session_ttl_seconds in defend.config.yaml controls how long session-related server state for the guard flow is retained (default in schema 300 seconds unless you override it). Tune it to match your product’s conversation length and memory requirements.

Inspection and deletion

For debugging and privacy workflows, the API exposes session inspection and deletion:

• GET /v1/sessions/:session_id - returns rolling scores and history metadata when found.
• DELETE /v1/sessions/:session_id - removes server-side session state.

See Sessions API.