Skip to main content
Sessions let InferenceWall track multi-turn conversation context across multiple scan calls. When you associate scan requests with a session, the detection pipeline can correlate inputs and outputs over time — improving accuracy for attacks that span several turns.

​
Using sessions in scan requests

Pass a session_id in the body of any scan or analyze request to associate it with a session: 
curl -X POST http://localhost:8000/v1/scan/input \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "What is the weather today?", "session_id": "user-session-abc123"}'
You can use any string as a session ID. Use a value that maps to the user’s conversation in your application — for example, a chat thread ID or user ID.

​
POST /v1/sessions

Create a new session explicitly to set a custom TTL or pre-register a session ID before your first scan.

​
Request

​
session_id
string
required
A unique identifier for the session. Use any string that maps to the user’s conversation in your application.
​
ttl_secs
number
default:"1800"
Session lifetime in seconds. The session is deleted automatically after this period of inactivity. Defaults to 1800 (30 minutes).

​
Response

Returns the created session object.

​
Example

curl -X POST http://localhost:8000/v1/sessions \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "user-session-abc123", "ttl_secs": 1800}'

​
GET /v1/sessions/

Retrieve the current state of a session by its ID.

​
Path parameters

​
id
string
required
The session ID to retrieve.

​
Example

curl http://localhost:8000/v1/sessions/user-session-abc123 \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY"

​
DELETE /v1/sessions/

Delete a session and clear its stored context. Use this when a conversation ends or when you want to reset the context for a user.

​
Path parameters

​
id
string
required
The session ID to delete.

​
Example

curl -X DELETE http://localhost:8000/v1/sessions/user-session-abc123 \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY"

​
Session TTL

Sessions expire automatically after ttl_secs seconds of inactivity (default: 1800 seconds / 30 minutes). You do not need to delete sessions manually — they are cleaned up automatically when they expire.
Set a shorter TTL for high-throughput deployments where old session data wastes memory, and a longer TTL for applications with long-lived conversations.

​
Distributed sessions with Redis

By default, sessions are stored in memory. In multi-instance deployments, this means a request routed to a different instance won’t see the session state created by another instance. To share sessions across instances, configure a Redis backend by setting the IW_REDIS_URL environment variable: 
export IW_REDIS_URL=redis://your-redis-host:6379
With Redis configured, all instances share the same session store, and routing is transparent to the detection pipeline.