> ## 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 a batch > Return a Firewall verdict for each independent event in input order. Send independent events in `texts`. For conversation-aware checks, use ordered [single-event requests](/docs/api-reference/classify) with the same `metadata.conversationId`. Batch classification neither reads nor updates conversation history. Use your provisioned `SILMARIL_API_URL` as the full request URL. Inspect `prediction` and optional `governance.action` for every item in `predictions` before consuming it. ```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 '{ "texts": [ "Summarize this release note.", "The release adds support for Python 3.12." ], "hooks": ["user_input", "tool_response"], "tool_names": [null, "read_file"], "metadata": [ {"conversationId": "conv-a"}, {"conversationId": "conv-b"} ] }' ``` ```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({ "texts": [ "Summarize this release note.", "The release adds support for Python 3.12.", ], "hooks": ["user_input", "tool_response"], "tool_names": [None, "read_file"], "metadata": [ {"conversationId": "conv-a"}, {"conversationId": "conv-b"}, ], }).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({ texts: [ "Summarize this release note.", "The release adds support for Python 3.12.", ], hooks: ["user_input", "tool_response"], tool_names: [null, "read_file"], metadata: [ { conversationId: "conv-a" }, { conversationId: "conv-b" }, ], }), signal: AbortSignal.timeout(10_000), }); if (!response.ok) { throw new Error(`Silmaril API error: ${response.status}`); } const result = await response.json(); console.log(result); ``` ## OpenAPI ````yaml api-reference/generated/batch.json POST /classify openapi: 3.1.0 info: title: Silmaril Firewall API — Classify a batch 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 a batch description: Return a Firewall verdict for each independent event in input order. operationId: classifyBatch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchRequest' examples: batch: summary: Independent events value: texts: - Summarize this release note. - The release adds support for Python 3.12. hooks: - user_input - tool_response tool_names: - null - read_file metadata: - conversationId: conv-a - conversationId: conv-b responses: '200': description: >- One verdict per text in the predictions array, in input order. Malicious or governance-blocked items still return HTTP 200. content: application/json: schema: $ref: '#/components/schemas/BatchResponse' examples: batch: summary: Batch value: predictions: - prediction: BENIGN score: 0.01 threshold: 0.5 - prediction: BENIGN score: 0.02 threshold: 0.5 '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: BatchRequest: title: Batch of independent events type: object required: - texts not: required: - text properties: texts: type: array minItems: 1 items: type: string minLength: 1 description: >- Independent events. Batch and input-size limits depend on your deployment. hooks: type: array items: $ref: '#/components/schemas/Hook' description: One hook per text, in input order. Length must match texts. tool_names: type: array items: type: - string - 'null' description: One tool name or null per text. Length must match texts. metadata: type: array items: oneOf: - $ref: '#/components/schemas/Metadata' - type: 'null' description: One metadata object or null per text. Length must match texts. resources: type: array items: oneOf: - $ref: '#/components/schemas/Resource' - type: 'null' description: >- One concrete resource or null per text, where supported. Length must match texts. identity_revision: type: string minLength: 1 description: Resource-catalog revision, where supported by the deployment. 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 BatchResponse: title: Batch verdicts type: object required: - predictions properties: predictions: type: array items: $ref: '#/components/schemas/Verdict' description: One verdict per text, in input order. 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. 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. 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. OutcomeScores: type: object additionalProperties: type: number minimum: 0 maximum: 1 description: >- Optional scores keyed by harmful outcome. Available keys depend on the deployment. 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.