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

# API Reference

> Classify user input, tool calls, tool responses, and model output over HTTP.

The Firewall API returns a verdict for each event your application checks. Use it directly over HTTP or through a [Silmaril SDK](/docs/start/quickstart).

## Get access

Silmaril provisions an API key and a classify URL for your deployment. [Book a call](https://cal.com/silmaril/30min) to arrange access, then set `SILMARIL_API_KEY` and `SILMARIL_API_URL` in your service environment.

`SILMARIL_API_URL` is the complete classify URL, including any deployment path prefix and `/classify`. Use the supplied value as-is. Hosted and self-hosted deployments use the same request format.

## Classify events

Send JSON with the `x-api-key` header to `POST /classify`.

| Request | Body | Response |
| - | - | - |
| [Single event](/docs/api-reference/classify) | `text` with optional hook, tool name, and metadata | One verdict |
| [Batch](/docs/api-reference/batch) | `texts` with optional arrays of hooks, tool names, and metadata | A `predictions` array in input order |

Batch items are independent. For conversation-aware checks, send ordered single-event requests with the same `metadata.conversationId`, waiting for each verdict before sending the next event.

## Handle the verdict

A successful HTTP response contains a verdict even when it is malicious. Check `prediction` and the optional `governance.action` before consuming the event. In Block mode, stop a malicious or governance-blocked event. In Warn or Shadow mode, record the would-block decision and continue according to your application policy.

`prediction` is the authoritative `BENIGN` or `MALICIOUS` verdict. The score and optional outcome fields add detail. Use [firewall outcomes](/docs/sdk/outcomes) to route malicious results.

A non-2xx response or network failure means no verdict was returned. Your application decides whether that boundary fails open or closed.

## AI gateways

LiteLLM uses a separate guardrail URL supplied with your deployment. Configure it through the [LiteLLM integration guide](/docs/integrations/litellm).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.