{% extends "base.html" %} {% block title %}API — {{ site_name }}{% endblock %} {% block content %}

API

JSON over HTTP, no authentication on a private deployment. Put it behind a reverse proxy — or an API gateway — if you expose it to the internet. Rate limit: {{ rate_limit }} requests per minute per IP.

Endpoints

MethodPathReturns
GET/api/v1/hash/<md5|sha1|sha256>verdict for a file hash
GET/api/v1/url?url=<url>verdict for a URL
GET/api/v1/domain?domain=<name>verdict for a domain
GET/api/v1/ip?ip=<addr>verdict for an IP address
GET/api/v1/lookup?q=<anything>auto-detects the indicator type
POST/api/v1/bulkqueue a bulk job, returns 202 + job id
GET/api/v1/bulk/<id>job status and verdict counts
GET/api/v1/bulk/<id>/itemsper-indicator results
GET/api/v1/sourcesconfigured sources and their state
GET/api/v1/statsinstance statistics
Append &fresh=1 to bypass the result cache.

Examples

# single hash
curl -s '{{ request.url_root }}api/v1/hash/44d88612fea8a8f36de82e1278abb02f' | jq .verdict

# URL
curl -s '{{ request.url_root }}api/v1/url?url=https%3A%2F%2Fexample.com%2Flogin' | jq '.verdict, .headline'

# bulk CSV
curl -s -F 'file=@feed.csv' -F 'label=weekly' {{ request.url_root }}api/v1/bulk

# poll
curl -s '{{ request.url_root }}api/v1/bulk/<job_id>' | jq .status

Response shape

{
  "indicator": { "kind": "hash", "value": "44d88612…", "raw": "44d88612…", "hashes": {"md5": "…"} },
  "verdict": "malicious",          // malicious | suspicious | clean | known_good | unknown
  "confidence": 75,
  "headline": "Listed as malicious by 2 independent sources",
  "score": 200,
  "corroboration": 2,
  "families": ["Emotet"],
  "evidence": [
    { "key": "blocklist", "label": "Blocklists", "answered": 2, "hit": 2,
      "sources": ["circl", "otx"] }
  ],
  "file_identity": { "name": "cmd.exe", "product": "Microsoft Windows",
                     "size": "304.0 KB", "source": "circl" },
  "elapsed_seconds": 0.54,
  "sources_checked": 2,
  "results": [
    { "source": "circl", "status": "found", "verdict": "malicious",
      "detections": 0, "total": 0, "note": "listed by malshare.com",
      "category": "reputation", "detail": {} }
  ]
}

Sources on this instance

{{ sources|selectattr('active')|list|length }} of {{ sources|length }} are active.

{% for s in sources %} {% endfor %}
SourceSupportsStatus
{{ s.name }} {{ s.kinds|join(', ') }} {% if s.state == 'active' %}active {% elif s.state == 'disabled' %}opt-in {% else %}needs key{% endif %}
{% endblock %}