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

# Classify an event

> Return a Firewall verdict for one complete event.

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

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

<RequestExample>
  ```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)
  ```

  ```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);
  ```
</RequestExample>


## 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
      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.01
                    threshold: 0.5
                    primary_outcome: benign
                malicious:
                  summary: Malicious event
                  value:
                    prediction: MALICIOUS
                    score: 0.98
                    threshold: 0.5
                    primary_outcome: secret_exposure
        '400':
          description: >-
            Invalid request body, metadata, or mismatched per-item arrays. No
            verdict.
        '403':
          description: >-
            The API key or request is not authorized for this deployment. No
            verdict.
        '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 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.
        threshold:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Scoring override for legacy runtimes. Cascade uses its 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: >-
            Classification score. Use prediction for the verdict instead of
            recomputing it from score.
        threshold:
          type: number
          minimum: 0
          maximum: 1
          description: Threshold reported by the deployment.
        primary_outcome:
          type: string
          enum:
            - benign
            - information_disclosure
            - secret_exposure
            - control_abuse
            - system_compromise
            - service_disruption
          description: >-
            Optional outcome detail. 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
              description: Matching governance rule, when present.
            policy_version:
              type: string
              description: Policy version used for the decision.
    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: Agent identity used by applicable governance policies.
                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.
    OutcomeScores:
      type: object
      additionalProperties:
        type: number
        minimum: 0
        maximum: 1
      description: >-
        Optional scores keyed by harmful outcome. Available keys depend on the
        deployment.
    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.