Skip to main content

Hermes API overview

Hermes analyses one complete email message and returns a compact security result. The public v1 surface has exactly one synchronous operation:

POST https://api.phishinghermes.com/v1/email-analyses

The documentation is public. API access is not anonymous or self-service: Hermes manually issues each credential for an approved organization, customer, environment, and capability. Integrations are server-to-server.

What you send​

Send the unchanged RFC 5322/MIME bytes with Content-Type: message/rfc822. Every request requires a valid X-API-Key and an Idempotency-Key for that one logical submission.

The credential selects the authorized customer. There is no customer selector in a header, query parameter, or payload.

What you receive​

A successful response contains:

  • an opaque analysis identifier;
  • verdict and risk classifications;
  • completeness, which states whether every applicable analysis area completed;
  • bounded signal_codes and warnings;
  • creation and public schema versions;
  • a request identifier for support and traceability.

Hermes deliberately omits tenant identifiers, internal scores, confidence, prompts, provider output, engine names, detailed evidence, thresholds, billing state, and infrastructure details.

Safe integration path​

  1. Request API access.
  2. Keep the issued key in a backend secrets manager.
  3. Follow the quickstart with the synthetic message.
  4. Interpret verdict, risk, completeness, signals, and warnings together.
  5. Retry only as described in Idempotency and Limits and retries.
Current scope

API v1 accepts complete email messages only. It does not provide URL-only analysis, SMS analysis, history, asynchronous retrieval, webhooks, reports, plugins, administration, diagnostics, QR features, or key-management endpoints.

Base URL and version​

Use this origin as the base URL:

https://api.phishinghermes.com

Append the operation path once: /v1/email-analyses. Do not configure /v1 in both the base URL and the operation path.

The version is part of the path. See API lifecycle before generating or upgrading a client.

Contract source​

The downloadable public OpenAPI document is the canonical machine-readable contract for this portal. The API Reference renders that same document in read-only mode.