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

# Classify an event

> Return a Firewall verdict for one complete event.

Send one complete event in `text`. For multiple independent events, use [batch classification](https://silmaril.security/docs/api-reference/batch.md).

Use your provisioned `SILMARIL_API_URL` as the full request URL. Inspect `prediction` and optional `governance.action` before consuming the event.

Choose cURL, TypeScript, JavaScript, Python, Go, or Java in the request examples. They use standard HTTP libraries; the Java example requires Java 17 or later.

```bash cURL theme={"theme":"github-light-default"}
curl --request POST "$SILMARIL_API_URL" \
  --header "x-api-key: $SILMARIL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "Summarize this release note.",
    "hook": "user_input",
    "metadata": {"conversationId": "conv-123"}
  }'
```

```python Python theme={"theme":"github-light-default"}
import json
import os
from urllib.request import Request, urlopen

request = Request(
    os.environ["SILMARIL_API_URL"],
    data=json.dumps({
        "text": "Summarize this release note.",
        "hook": "user_input",
        "metadata": {"conversationId": "conv-123"},
    }).encode("utf-8"),
    headers={
        "x-api-key": os.environ["SILMARIL_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)

with urlopen(request, timeout=10) as response:
    result = json.load(response)

print(result)
```

```typescript TypeScript theme={"theme":"github-light-default"}
const response = await fetch(process.env.SILMARIL_API_URL!, {
  method: "POST",
  headers: {
    "x-api-key": process.env.SILMARIL_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Summarize this release note.",
    hook: "user_input",
    metadata: { conversationId: "conv-123" },
  }),
  signal: AbortSignal.timeout(10_000),
});

if (!response.ok) {
  throw new Error(`Silmaril API error: ${response.status}`);
}

const result = await response.json();
console.log(result);
```

```javascript JavaScript theme={"theme":"github-light-default"}
const response = await fetch(process.env.SILMARIL_API_URL, {
  method: "POST",
  headers: {
    "x-api-key": process.env.SILMARIL_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    text: "Summarize this release note.",
    hook: "user_input",
    metadata: { conversationId: "conv-123" },
  }),
  signal: AbortSignal.timeout(10_000),
});

if (!response.ok) {
  throw new Error(`Silmaril API error: ${response.status}`);
}

const result = await response.json();
console.log(result);
```

```go Go theme={"theme":"github-light-default"}
package main

import (
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func main() {
    if err := classify(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

func classify() error {
    body := `{
  "text": "Summarize this release note.",
  "hook": "user_input",
  "metadata": {
    "conversationId": "conv-123"
  }
}`
    request, err := http.NewRequest(http.MethodPost,
        os.Getenv("SILMARIL_API_URL"), strings.NewReader(body))
    if err != nil {
        return err
    }
    request.Header.Set("x-api-key", os.Getenv("SILMARIL_API_KEY"))
    request.Header.Set("Content-Type", "application/json")

    client := &http.Client{
        Timeout: 10 * time.Second,
        CheckRedirect: func(*http.Request, []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil {
        return err
    }
    defer response.Body.Close()
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("Silmaril API error: %d", response.StatusCode)
    }
    _, err = io.Copy(os.Stdout, response.Body)
    return err
}
```

```java Java theme={"theme":"github-light-default"}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ClassifyRequest {
    public static void main(String[] args) throws Exception {
        var client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        var body = """
            {
              "text": "Summarize this release note.",
              "hook": "user_input",
              "metadata": {
                "conversationId": "conv-123"
              }
            }
            """;
        var request = HttpRequest.newBuilder(URI.create(System.getenv("SILMARIL_API_URL")))
            .timeout(Duration.ofSeconds(10))
            .header("x-api-key", System.getenv("SILMARIL_API_KEY"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("Silmaril API error: " + response.statusCode());
        }
        System.out.println(response.body());
    }
}
```

```json theme={"theme":"github-light-default"}
{
  "prediction": "BENIGN",
  "score": 0.98,
  "threshold": 0.5,
  "primary_outcome": "benign"
}
```

A high confidence score can accompany `BENIGN`. See [confidence scores](https://silmaril.security/docs/guides/enforcement.md#confidence-scores) for interpretation and threshold behavior.

## Handle the verdict

HTTP `200` returns a classification. In Block mode, stop an event when `prediction` is `MALICIOUS` or `governance.action` is `block`. In Warn or Shadow mode, record the would-block decision and continue.

Handle request failures with your application's [error policy](https://silmaril.security/docs/operate/troubleshooting.md). See [modes and enforcement](https://silmaril.security/docs/guides/enforcement.md) for the full decision model.

## Optional review depth

The optional top-level `review` field accepts `standard` or `deep`. See [review depth](https://silmaril.security/docs/guides/review-depth.md) for requirements, selection behavior, and acknowledgement rules.


## OpenAPI

````yaml api-reference/generated/classify.json POST /classify
openapi: 3.1.0
info:
  title: Silmaril Firewall API — Classify an event
  version: 1.0.0
  description: >-
    Public classification contract used by the Silmaril SDKs. Use the complete
    classify URL provisioned for your deployment. Optional fields depend on the
    runtime and its configuration.
servers:
  - url: https://your-deployment.example.com
    description: Replace with your deployment origin and any path prefix before /classify.
security:
  - apiKey: []
paths:
  /classify:
    post:
      summary: Classify an event
      description: Return a Firewall verdict for one complete event.
      operationId: classifyEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleRequest'
            examples:
              single:
                summary: Single event
                value:
                  text: Summarize this release note.
                  hook: user_input
                  metadata:
                    conversationId: conv-123
              singleStandard:
                summary: Single event with standard review
                value:
                  text: Summarize this release note.
                  hook: user_input
                  review: standard
                  metadata:
                    conversationId: conv-123
      responses:
        '200':
          description: >-
            One verdict. A malicious or governance-blocked result still returns
            HTTP 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verdict'
              examples:
                benign:
                  summary: Benign event
                  value:
                    prediction: BENIGN
                    score: 0.98
                    threshold: 0.5
                    primary_outcome: benign
                  description: >-
                    High confidence in a safe assessment with a final BENIGN
                    verdict.
                malicious:
                  summary: Malicious event
                  value:
                    prediction: MALICIOUS
                    score: 0.98
                    threshold: 0.5
                    primary_outcome: secret_exposure
                benignStandard:
                  summary: Benign event with standard review acknowledged
                  value:
                    prediction: BENIGN
                    score: 0.98
                    threshold: 0.5
                    primary_outcome: benign
                    review: standard
                  description: >-
                    High confidence in a safe assessment with a final BENIGN
                    verdict.
        '400':
          description: >-
            Invalid request body, metadata, or mismatched per-item arrays.
            review must be the exact string standard or deep; null, other types,
            whitespace or case variants, and other strings are invalid. deep
            also returns HTTP 400 before classification when deep review is
            unavailable for the selected deployment. An explicit deep selection
            overrides a standard-review default. standard is available on all
            deployments. No verdict.
        '401':
          description: >-
            The direct Rust runtime reports a missing API key. Direct Python
            HTTP routes with API-key authentication enabled and hosted gateways
            can return 403 instead. No verdict.
        '403':
          description: >-
            The direct Rust runtime reports an invalid API key, unauthorized
            traffic class, or conflicting forced surface. Direct Python HTTP
            routes with API-key authentication enabled and hosted gateways can
            report either a missing or invalid key as 403. No verdict.
        '408':
          description: >-
            The direct Firewall runtime returns this response when the deadline
            for receiving the request body expires. Classification does not run
            and no verdict is produced. The connection is closed. Do not treat
            this response as a verdict. Python and Go SDKs intentionally retry
            HTTP 408 by default; Python supports max_retries=0 to disable
            retries, and Go callers can bound attempts with context cancellation
            or deadlines. The TypeScript SDK retries HTTP 429 only and surfaces
            HTTP 408 as an API error. This pre-classification timeout does not
            establish replay safety for model or tool operations.
          headers:
            Connection:
              description: >-
                The direct Firewall runtime closes the connection after this
                response.
              schema:
                type: string
                const: close
              example: close
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                  - code
                additionalProperties: false
                properties:
                  detail:
                    type: string
                    const: request body deadline exceeded
                  code:
                    type: string
                    const: request_body_timeout
              example:
                detail: request body deadline exceeded
                code: request_body_timeout
        '413':
          description: Request exceeds the deployment's body-size limit. No verdict.
        '429':
          description: Gateway rate limit or quota reached. Retry with backoff. No verdict.
        '500':
          description: Internal classification error. No verdict.
        '503':
          description: >-
            Classification service or authorization policy is unavailable or not
            ready. No verdict.
components:
  schemas:
    SingleRequest:
      title: Single event
      type: object
      required:
        - text
      not:
        required:
          - texts
      properties:
        text:
          type: string
          minLength: 1
          description: >-
            One complete event to classify. Input-size limits depend on your
            deployment.
          example: Summarize this release note.
        hook:
          $ref: '#/components/schemas/Hook'
        tool_name:
          type: string
          description: Tool name when checking a tool call or tool response.
          example: read_file
        metadata:
          $ref: '#/components/schemas/Metadata'
        resource:
          $ref: '#/components/schemas/Resource'
        identity_revision:
          type: string
          minLength: 1
          description: >-
            Resource-catalog revision for deployments supporting concrete
            governance identities.
        review:
          $ref: '#/components/schemas/ReviewLevel'
        threshold:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Scoring override for older deployments. Current deployments use
            their configured decision policy. Use the returned prediction as the
            verdict.
          x-mint:
            post:
              - Legacy
        temperature:
          type: number
          minimum: 0.01
          maximum: 10
          description: >-
            Score calibration for legacy runtimes. Support depends on your
            deployment.
          x-mint:
            post:
              - Legacy
    Verdict:
      title: Single verdict
      type: object
      required:
        - prediction
        - score
        - threshold
      additionalProperties: true
      properties:
        prediction:
          type: string
          enum:
            - BENIGN
            - MALICIOUS
          description: Authoritative verdict. Also check governance.action when present.
        score:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Score from 0 to 1 expressing confidence in the model assessment as
            harmful, safe, or uncertain. A high-confidence safe assessment can
            return BENIGN. Where present, malicious_score is an alias. Route on
            prediction and applicable governance.action. See [confidence
            scores](/guides/enforcement#confidence-scores).
        threshold:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Threshold reported by the deployment. The configured confidence
            threshold applies to potentially harmful events with available
            confidence, using the value before display rounding; equality
            passes. Your policy determines how results below the threshold are
            handled. See [confidence
            scores](/guides/enforcement#confidence-scores).
        primary_outcome:
          type: string
          examples:
            - benign
            - information_disclosure
            - secret_exposure
            - control_abuse
            - system_compromise
            - service_disruption
          description: >-
            Optional forward-compatible outcome detail. The examples are known
            legacy labels, not a closed enum. Prediction remains authoritative;
            a missing or unknown malicious outcome should be blocked by default
            in Block mode.
        outcome_scores:
          $ref: '#/components/schemas/OutcomeScores'
        detector_scores:
          $ref: '#/components/schemas/OutcomeScores'
        detector_counts:
          type: object
          additionalProperties:
            type: integer
            minimum: 0
          description: Optional detection counts keyed by harmful outcome.
        governance:
          type: object
          required:
            - action
            - policy_version
          description: Optional governance decision. Older deployments may omit this field.
          properties:
            action:
              type: string
              enum:
                - allow
                - block
              description: Applicable governance-policy verdict.
            rule_id:
              type:
                - string
                - 'null'
              description: Matching governance rule, when present.
            policy_version:
              type: string
              description: Policy version used for the decision.
              minLength: 1
            resource:
              oneOf:
                - $ref: '#/components/schemas/GovernanceDecisionResource'
                - type: 'null'
              description: >-
                Canonical resource evidence for schema-6 decisions. Older
                deployments and unresolved identities may omit this field.
            identity_revision:
              type:
                - string
                - 'null'
              description: >-
                Open-ended identity-catalog revision used for the decision, when
                available.
            reason:
              type:
                - string
                - 'null'
              description: >-
                Open-ended decision reason supplied by the runtime, such as
                identity_unresolved.
        review:
          $ref: '#/components/schemas/ReviewLevel'
          description: >-
            On a single response, this top-level field acknowledges an explicit
            request selection. Within a batch prediction, this field is not the
            batch acknowledgement; use BatchResponse.review. It confirms the
            applied setting. An event may complete without additional review.
    Hook:
      type: string
      description: Boundary being checked. Use the SDK hook labels shown here.
      enum:
        - user_input
        - system_prompt
        - tool_call
        - tool_response
        - llm_output
        - unknown
      example: user_input
    Metadata:
      type: object
      additionalProperties: true
      description: >-
        JSON metadata for this event. SDKs add request identity under silmaril.
        A conversationId connects ordered single-event calls when conversation
        history is supported. Batch metadata does not connect events into a
        sequence.
      properties:
        conversationId:
          type: string
          description: >-
            Caller-owned conversation identity. Reuse for ordered single-event
            checks.
          example: conv-123
        silmaril:
          type: object
          additionalProperties: true
          description: Request identity and optional SDK-compatible governance context.
          properties:
            request_id:
              type: string
              minLength: 1
              description: Event identifier. SDKs generate this value per request.
            governance:
              type: object
              properties:
                agent:
                  type: string
                  description: >-
                    Caller attribution only; setting this field does not
                    activate or select agent-scoped rules. The authenticated
                    principal binding configured by the server selects the agent
                    identity used for policy evaluation.
                resource:
                  $ref: '#/components/schemas/GovernanceContextResource'
    Resource:
      type: object
      required:
        - kind
        - id
      additionalProperties: false
      description: >-
        Concrete governance resource, where supported. id must not be blank.
        mcp_tool requires parent_id; other resource kinds must omit parent_id.
      if:
        properties:
          kind:
            const: mcp_tool
        required:
          - kind
      then:
        required:
          - parent_id
      else:
        not:
          required:
            - parent_id
      properties:
        kind:
          type: string
          enum:
            - agent
            - tool
            - mcp_server
            - mcp_tool
            - plugin
            - skill
            - extension
        id:
          type: string
          minLength: 1
          pattern: .*\S.*
        parent_id:
          type: string
          minLength: 1
          pattern: .*\S.*
          description: Required for mcp_tool and omitted for other kinds.
    ReviewLevel:
      type: string
      enum:
        - standard
        - deep
      description: >-
        Optional request-wide review selection. standard selects standard
        review. deep requests an additional review of eligible potentially
        harmful events when available on your deployment. An event may complete
        without additional review. Omit review to inherit the deployment
        default. Review depth is independent of enforcement mode.
      example: deep
    OutcomeScores:
      type: object
      additionalProperties:
        type: number
        minimum: 0
        maximum: 1
      description: >-
        Optional scores keyed by harmful outcome. Available keys depend on the
        deployment.
    GovernanceDecisionResource:
      type: object
      required:
        - kind
        - id
      description: >-
        Canonical resource evidence returned with a schema-6 governance
        decision. Older deployments and unresolved identities can omit the
        entire resource field.
      if:
        properties:
          kind:
            const: mcp_tool
        required:
          - kind
      then:
        required:
          - parent_id
        properties:
          parent_id:
            type: string
            minLength: 1
            pattern: .*\S.*
      else:
        properties:
          parent_id:
            type: 'null'
      properties:
        kind:
          type: string
          enum:
            - agent
            - tool
            - mcp_server
            - mcp_tool
            - plugin
            - skill
            - extension
        id:
          type: string
          minLength: 1
          pattern: .*\S.*
          description: Canonical resource identifier.
        parent_id:
          description: >-
            Canonical parent resource identifier. Required for MCP tools. Other
            resource kinds omit this field or return null.
    GovernanceContextResource:
      type: object
      required:
        - kind
      description: >-
        SDK-compatible resource context. Support depends on the deployment's
        governance policy.
      properties:
        kind:
          type: string
          enum:
            - agent
            - tool
            - mcp_server
            - mcp_tool
            - plugin
            - skill
            - extension
        id:
          type: string
          description: Resource identifier.
        parent_id:
          type: string
          description: MCP server identifier for an MCP tool.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key provisioned for your deployment.

````

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