> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inferwall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Management API Endpoints

> Create and manage InferenceWall sessions to track multi-turn conversation context, improving detection accuracy for attacks that span multiple turns.

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:

```bash theme={null}
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

<ParamField body="session_id" type="string" required>
  A unique identifier for the session. Use any string that maps to the user's conversation in your application.
</ParamField>

<ParamField body="ttl_secs" type="number" default="1800">
  Session lifetime in seconds. The session is deleted automatically after this period of inactivity. Defaults to `1800` (30 minutes).
</ParamField>

### Response

Returns the created session object.

### Example

```bash theme={null}
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/{id}

Retrieve the current state of a session by its ID.

### Path parameters

<ParamField path="id" type="string" required>
  The session ID to retrieve.
</ParamField>

### Example

```bash theme={null}
curl http://localhost:8000/v1/sessions/user-session-abc123 \
  -H "Authorization: Bearer iwk_scan_YOUR_KEY"
```

***

## DELETE /v1/sessions/{id}

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

<ParamField path="id" type="string" required>
  The session ID to delete.
</ParamField>

### Example

```bash theme={null}
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.

<Tip>
  Set a shorter TTL for high-throughput deployments where old session data wastes memory, and a longer TTL for applications with long-lived conversations.
</Tip>

## 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:

```bash theme={null}
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.