InferenceWall REST API Overview

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:

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:

{
  "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:

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

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

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

​Base URL

​API versioning

​Request format

​Response format

​HTTP status codes

​Authentication

​Endpoint groups

Base URL

API versioning

Request format

Response format

HTTP status codes

Authentication

Endpoint groups