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

# InferenceWall REST API Overview

> The InferenceWall REST API exposes scan, analyze, session, signature, policy, health, and admin endpoints — all returning JSON over HTTP at port 8000.

InferenceWall exposes a REST API at port 8000 for scanning LLM inputs and outputs, managing sessions, inspecting signatures and policies, and checking server health. All endpoints accept and return JSON, and follow a consistent response structure across every route.

## Base URL

```
http://localhost:8000
```

Replace `localhost` with your deployed host when running InferenceWall in a non-local environment.

## API versioning

All endpoints are prefixed with `/v1/`:

```
http://localhost:8000/v1/scan/input
http://localhost:8000/v1/health
```

## Request format

Send all request bodies as JSON with the `Content-Type: application/json` header:

```bash theme={null}
curl -X POST http://localhost:8000/v1/scan/input \
  -H "Content-Type: application/json" \
  -d '{"text": "What is the weather today?"}'
```

## Response format

Every response is JSON. Scan and analyze endpoints return a consistent structure:

```json theme={null}
{
  "decision": "allow",
  "score": 0.0,
  "matches": [],
  "request_id": "req-1712345678000"
}
```

| Field        | Type                         | Description                                                            |
| ------------ | ---------------------------- | ---------------------------------------------------------------------- |
| `decision`   | `allow` \| `flag` \| `block` | The firewall verdict for this request.                                 |
| `score`      | number                       | Anomaly score. Computed as `confidence × severity` across all matches. |
| `matches`    | array                        | List of matched signatures. Empty when no threats are detected.        |
| `request_id` | string                       | Unique identifier for this request, for correlation and logging.       |

## HTTP status codes

| Code  | Meaning                                                            |
| ----- | ------------------------------------------------------------------ |
| `200` | Success — the request was processed and a result is returned.      |
| `400` | Invalid request — the request body is malformed or missing fields. |
| `401` | Unauthorized — the API key is missing or invalid.                  |
| `422` | Validation error — the request body failed schema validation.      |
| `500` | Server error — an unexpected error occurred on the server.         |

## Authentication

InferenceWall uses API key authentication with two roles: `scan` and `admin`. Pass your key in the `Authorization` header:

```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?"}'
```

<Note>
  If `IW_API_KEY` is not set, authentication is disabled. This is fine for local development but you should always enable auth in production.
</Note>

See [Authentication](/api/authentication) for full details on key types, roles, and generating keys.

## Endpoint groups

| Group          | Base path                   | Description                                                    |
| -------------- | --------------------------- | -------------------------------------------------------------- |
| **Scan**       | `/v1/scan/*`                | Detect threats in LLM inputs and outputs.                      |
| **Analyze**    | `/v1/analyze/*`             | Scan with additional PII detection detail.                     |
| **Health**     | `/v1/health/*`              | Liveness, readiness, and full status probes.                   |
| **Signatures** | `/v1/signatures/*`          | List and inspect loaded detection signatures.                  |
| **Sessions**   | `/v1/sessions/*`            | Create and manage multi-turn conversation sessions.            |
| **Policies**   | `/v1/policies`              | List loaded policy profiles and their configuration.           |
| **Auth**       | `/v1/auth/*`                | Login, logout, and session check for admin access.             |
| **Admin**      | `/v1/admin/*`, `/v1/config` | Hot-reload config, view statistics, and read runtime settings. |