Result model

A 200 response is terminal for the public transaction. It does not by itself mean that every applicable analysis area completed: always check completeness and warnings.

Public fields

Field	Meaning
analysis_id	Opaque identifier for the analysis
status	Always completed in public v1 success responses
verdict	phishing, suspicious, no_threat_detected, or inconclusive
risk	high, medium, none, or unknown
completeness	complete or partial
signal_codes	Bounded, generic public reasons
warnings	Accepted-input or incomplete-analysis conditions
created_at	UTC creation timestamp
schema_version	Public response schema version, currently 1.0 by default, or opt-in 1.1
request_id	8–80 character correlation identifier for support

Security-preserving partiality

Situation	Public behavior
Confirmed threat and all applicable analysis completes	Preserve phishing or suspicious; complete
Confirmed threat and an applicable area is incomplete	Preserve the threat; partial plus the applicable warning
Apparently benign result and an applicable area is incomplete	inconclusive, unknown, partial, plus warning
An analysis area has no applicable input	Does not cause partiality by itself
Applicable timeout, error, unexpected absence, unknown state, or configuration skip	Causes partial
No usable analysis result	Safe RFC 9457 Problem, not a success object

Hermes does not label an incompletely analysed message as no_threat_detected.

Signal codes

• suspicious_link
• brand_impersonation
• unsafe_attachment
• suspicious_content
• suspicious_message

Warning codes

• malformed_message_accepted
• invalid_utf8_replaced
• analysis_completeness_unknown
• sender_authentication_incomplete
• content_analysis_incomplete
• link_analysis_incomplete
• attachment_analysis_incomplete

Input-format warnings can coexist with complete analysis. Incomplete-analysis warnings require partial.

Decision order

1. Verify the HTTP status and schema_version.
2. Read verdict and risk.
3. Check completeness and every warning.
4. Use signal_codes for explanation, routing, and observability.
5. Preserve analysis_id and request_id in redacted operational records.

The current success and Problem schemas use additionalProperties: false; fields outside the published schema are not part of this contract. Enum values are also closed. Treat an unknown field or enum as a contract mismatch until you review an updated OpenAPI document.

Opt-in evidence summary (1.1)

Send X-Hermes-Response-Version: 1.1 to receive an additional, bounded evidence_summary. Omitting the header preserves response 1.0. All four published clients support the optional environment setting HERMES_RESPONSE_VERSION=1.1; their default remains 1.0.

Inspect the response's actual schema_version. During a controlled rollback an older server may return 1.0 without the summary: retain that original result and report the explanation as unavailable. The clients warn explicitly; they do not submit another analysis or create another operation key to recover the summary.

The summary explains evidence already produced and persisted for the same analysis. It does not run the detector, call a provider, improve a partial result, or account another analysis. It keeps verdict, risk and analysis completeness unchanged.

• reasons describes supported signals, interpretations, review context or a recorded contribution; it does not invent a decisive cause.
• observations separates neutral facts and executed checks from threat reasons.
• sources uses local references to the body, MIME occurrence, document/page, contextual URL or message headers. It excludes raw message content, full URLs, addresses, account values, filenames and globally correlatable hashes.
• limitations gives a controlled cause and action. An optional commercial verification not performed does not itself reduce technical completeness.
• Construction metadata distinguishes a summary frozen at analysis completion from the first explicit projection of a historical result.

available means explainable recorded evidence, not unlimited inspection or a guarantee of safety. A complete benign analysis may normally have no threat reasons. limited describes missing explanation detail; unavailable means the retained metadata or its version cannot support a compatible explanation. Always read analysis completeness independently.

Locations describe their actual representation and unit. A position in extracted or normalized Unicode text is not a byte offset into the original EML. Page counts are published as inspected only when the reader records that fact: text-bearing pages and OCR pages can overlap and do not prove the number inspected.

projection_version, construction_origin and UTC constructed_at identify how the summary was frozen. Legacy snapshots may lack a construction timestamp; the service does not invent the original construction time. The current offset representation is segmenter_input_text, counted in unicode_code_points. Offsets are omitted when that precision was not recorded.

Human and policy controls still apply

Security classifications can contain false positives or false negatives. Do not describe any result as certainty, and handle partial results conservatively.