Threatera API
Threatera exposes everything the web UI does as a documented REST API. Upload and analyze files, detonate samples in an isolated sandbox, scan URLs, and pivot across the indicator graph — all over HTTP with JSON.
Base URL
All endpoints are served from the same host as the web app, under the /api prefix:
https://app.threatera.eu/api
Examples on this page use https://app.threatera.eu and the environment variable $THREATERA_KEY for your API key. Requests and responses are JSON unless noted (file upload is multipart; downloads are binary).
Authentication
Every endpoint (except /health) requires authentication. There are three accepted credentials, in order of precedence:
| Method | Header | Use for |
|---|---|---|
| Service key | x-api-key: <key> | Server-to-server automation and integrations |
| Personal API key | x-api-key: <key> | Per-user scripting (create under API keys) |
| Bearer JWT | Authorization: Bearer <token> | The web UI (from /auth/login) |
For API clients, send your key in the x-api-key header:
curl https://app.threatera.eu/api/stats \ -H "x-api-key: $THREATERA_KEY"
A missing or invalid credential returns 401 Unauthorized. Admin-only endpoints return 403 Forbidden for non-admins.
Roles, and what each one may do
Membership of an organisation carries a role, ranked read-only < analyst < admin < owner.
| Role | May |
|---|---|
read-only | read everything in the organisation. Every endpoint that changes data returns 403 — uploads, analyses, detonations, cases, comments, indicators, rules, watchlists and API keys. Changing one's own password and enrolling MFA are always permitted. |
analyst | everything above, plus every write. |
admin | everything above, plus the organisation's own administration: members, invites, the audit log. |
owner | as admin. Distinguished for member management — nobody may grant or remove a role at or above their own. |
read-only was enforced nowhere until 2026-08-18. The rank existed and the comparison function was correct, but every caller asked whether the actor was an admin, so the only line drawn was admin/not-admin: a read-only member could upload samples, run detonations and mint API keys. If you issued that role expecting it to restrict anything, it did not. tests/test_write_permission.py now walks the live route table and fails the build for any endpoint that changes data without saying who may call it.An API key inherits the role of the member who created it, so a key minted by an analyst can write and one minted under a read-only membership cannot. The shared service key writes by default — an ingestion integration that cannot submit a file has no purpose — and is separately barred from the admin surface unless SERVICE_KEY_ALLOWS_ADMIN is set.
Two-factor authentication
User accounts can enrol an authenticator app. Once enrolled, POST /api/auth/login needs the 6-digit code alongside the password; if it is missing the response is 200 with { "mfa_required": true } and no token, so a client can prompt for it and retry. Each code works once: a code accepted at sign-in or at enrollment is refused if presented again, with 401 “that code has already been used” — wait for the next one. Without this a code was good for its whole ~90-second window, to anyone who saw it. See Two-factor auth.
x-api-key clients are unaffected by a user's MFA state — which is what makes them the right credential for automation.Liveness
| Method & path | Description |
|---|---|
GET /health | The one unauthenticated endpoint. Returns { "status": "ok" }. |
Note it is not under the /api prefix. This is a process liveness probe for load balancers and container orchestration — for the state of the backing services (Postgres, Elasticsearch, ClamAV…) see System health.
Command line
threatera.py is the API from a terminal or a build pipeline: one file of Python 3.10+ standard library, nothing to install. The key goes in the x-api-key header and is never printed; TLS is always verified.
No Python on the machine? The same program is served built, with Python inside it, for a collector on a server that has none — most Windows servers: collector/threatera-windows-x64.zip, collector/threatera-macos-universal.tar.gz (Apple silicon and Intel) and collector/threatera-linux-x64.tar.gz (glibc 2.31 or newer: Debian 11, Ubuntu 20.04, RHEL 9 and later), under this guide's address. Each unpacks to a folder threatera/ holding the threatera program; use it wherever the examples say python3 threatera.py, and --version says standalone. collector/manifest.json lists what this installation serves, with each archive's version and SHA-256, and collector/SHA256SUMS the same for sha256sum -c; an installation without builds serves neither. Organisation › Collectors › New collector gives the exact steps. The builds are not code-signed: Windows asks once if a person starts it from a browser download, and a download made with curl, as the steps do, carries no mark for Windows or macOS to ask about.
curl -O "https://app.threatera.eu/guide/threatera.py" export THREATERA_URL=https://app.threatera.eu export THREATERA_KEY=ttk_… # Organisation › API keys
| Command | Does |
|---|---|
upload FILE [--deep] [--tag T] [--wait S] [--fail-on suspicious|malicious] | Uploads it. --wait waits up to S seconds for the analysis (queueing one if the upload did not) and prints the verdict. |
file SHA256 [--fail-on …] | The platform's verdict and an analyst's, side by side. |
ioc VALUE | What an analyst here decided, which feeds list it, and its reputation. |
blocklist CASE [--format txt|csv|defender|json] [--type …] | A case's block list to stdout — --format txt --type domain > list.txt for a firewall's external list. |
inbox [--mine|--unclaimed] [--kind …] | What is waiting for a person. |
watch FOLDER [--name …] [--interval 60] [--recursive] [--deep] [--mail] [--once] | A collector: sends every new file that appears in the folder, once, after asking which your organisation already holds, and checks in every interval. A mail message (.eml, .msg, or a file starting with mail headers) goes to the mail analysis and the Email tab instead; --mail sends every file that way, for a mail gateway’s quarantine. Remembers what it handled in ~/.threatera/; a file the platform refuses (a 4xx) is not retried until it changes; one it could not take — unreachable, a 5xx while it restarts, asked to slow down — is sent on the next pass. |
service FOLDER --name … [--mail] [--recursive] [--platform systemd|launchd|windows] [--user U] [--install] | Keeps a collector running: writes a systemd unit, a launchd daemon or a Windows scheduled task that starts watch at boot and restarts it when it stops (the Windows task with no time limit, which Task Scheduler otherwise sets at 72 hours). Needs --key-file: the service reads its key from that file, never from its command line. Prints the definition, or with --install writes it where it belongs and prints the commands that start it. Under systemd it runs as a throwaway account with the system read-only; --user runs it as an account that can read a folder others cannot. The script runs isolated (python -I), so nothing placed beside it is imported. On Windows the task runs as SYSTEM, so the folder is closed to everyone but SYSTEM and Administrators first — the printed steps start with that icacls line; a collector set up before 1.6 should run it and --install again. Organisation › Collectors › New collector shows the exact steps for each system. |
federate FILE | Contributes to early warning without uploading anything: each line — a domain, an IP address or a SHA-256 — is blinded on this machine, so the platform sees a group element and stores a token and a share it cannot read. - reads standard input. Says how many were accepted and how many three organisations already hold. |
warnings | The values you contributed that three or more organisations now hold, with the band of holders. |
save-key PATH | Asks for an API key without echoing it and writes it to PATH, readable by this account only — so a key never sits in shell history or a process list. On Windows, restrict the file with icacls as it says (by SID, so it works on a translated Windows). |
--key-file PATH reads the key from a file instead of THREATERA_KEY, and warns if other accounts can read it. --json prints what the API answered. --org (or THREATERA_ORG) names the organisation for a key that may act in several.
0 done; 1 the request failed or was refused, with the server's reason on stderr; 2 the command line was wrong; 3 --fail-on was met; 4 --wait ran out before the analysis finished. "Could not say" is never 0: a gate that failed open would ship the build it exists to stop.python3 threatera.py upload dist/installer.exe --deep --wait 600 --fail-on suspiciousConventions & errors
- Identifiers. Files are identified by their SHA-256 hash (lowercase hex). Indicators are identified by their value (an IP or domain).
- Deduplication. Files and indicators are deduplicated. Re-submitting an existing one bumps a sighting
counterand refresheslast_seenrather than creating a duplicate. - Async work. Analysis, detonation and URL scans are queued. The submit call returns
202 Acceptedwith apendingrecord; poll the matchingGETuntilstatusbecomescompleted/failed. - Pagination. List endpoints take
limit(1–200) andoffset, and return{ "total": n, "results": [...] }. The file and indicator listings are served from the search index, which pages no further than 10,000 results: past that,offset + limitanswers400saying so, and narrowing the filters reaches the rest. - Text. A NUL character (U+0000) cannot be stored, so a request carrying one — in the path, the query or a JSON body — is refused with
400. Content the platform ingests, such as a reported message's subject, keeps the rest of the text with the NUL shown as U+FFFD. A read that meets one already stored is answered500: that one is ours to fix, not yours. - Timestamps. ISO-8601 UTC.
Status codes
| Code | Meaning |
|---|---|
200 / 201 | Success |
202 | Accepted — async job queued |
204 | Success, no content (deletes) |
400 | Bad request (e.g. invalid hash / indicator) |
401 / 403 | Unauthorized / forbidden |
404 | Not found |
413 | Upload too large, or any other request body over 16 MB |
422 | Validation error (malformed body/params) |
429 | Too many requests — see Rate limits |
Rate limits
Three things are rate-limited: the routes a stranger could use to guess a password, uploads, and the sandbox. Everything else is not.
| Route | Limit | Counted per |
|---|---|---|
POST /api/auth/login | 10 a minute | For a browser that has not signed in to this account before, two budgets at once: the client address, and the account being signed in to — so changing address buys no more guesses against one account. A browser that has signed in to it before sends its known-device token and spends a budget of its own instead, so someone trying passwords cannot lock the owner out. |
POST /api/auth/registerPOST /api/auth/signupGET /api/auth/signup/pendingPOST /api/auth/signup/completePOST /api/auth/forgot-passwordPOST /api/auth/reset-passwordPOST /api/auth/mfa/activatePOST /api/auth/change-password | 10 a minute | Client address — one budget shared by these routes and by sign-ins from unrecognised browsers |
GET /api/trust/check/{token}GET /trust/check/{token} | 10 a minute | Client address — a budget of its own, so checking a report spends nobody’s sign-in attempts |
POST /api/files/upload | 60 a minute | Client address |
Detonations:POST /api/files/{sha256}/detonatePOST /api/sandbox/runs/rerunand a deep upload's detonation | 60 an hour | Organisation, one per run queued — a re-run of forty spends forty. A file the sandbox cannot run is refused before it counts. |
URL scans:POST /api/urlscansPOST /api/sandbox/runs/rerun | 120 an hour | Organisation, one per scan queued. A URL refused by the address check does not count. |
Over a limit, a request is refused with 429 and a Retry-After header: the seconds until the window resets. Windows are fixed — whole minutes or whole hours — rather than sliding, so a burst across a boundary can briefly get up to twice the limit through. Honour Retry-After rather than retrying at once.
The sandbox is limited per organisation because it is shared capacity, and two places answer differently from a plain 429, so that nothing is lost:
- A re-run queues the runs that fit and lists the rest in
failed, each with the seconds to wait. - A deep upload is stored and analysed regardless. If its detonation could not be queued,
not_queued.detonationin the response says so and when to start it from the file.
GET /api/tenants/current). Going over one refuses the upload with 413 and an X-Quota-Exceeded header naming which: uploads or storage.Universal search
One query across files, indicators, URLs, URL scans, cases, the watchlist, reported mail, campaigns, detection rules — and inside the samples and mail themselves — the endpoint to reach for when you have a string and don't yet know what it is. The search box in the platform's header (Ctrl/⌘ K) reads this endpoint, as the Search tab does.
The query is classified first, and only the stores that could plausibly match it are queried — a SHA-256 doesn't trigger a pointless URL scan. The classification is returned as detected so you can see how your input was read.
Query parameters
| Name | Type | Description |
|---|---|---|
| q required | string | A SHA-256 or a prefix of one, an IP, a domain, a URL, or free text. 1–512 chars. |
| limit | integer | Max results per category. 1–50, default 10. |
What each query type searches
detected | Searches, besides the five below |
|---|---|
sha256 / hash_prefix | Files, by hash or hash prefix |
ip | Indicators, by value prefix |
domain | Indicators; URL indicators on that host; URL scans whose URL contains it |
url | URL scans by URL prefix; the URL indicator for exactly that URL |
text | Filenames (substring); indicator values (prefix); URL indicators and scanned URLs (substring) |
Whatever the query is read as, five more are searched for it as a case-insensitive substring: cases (reference, title, summary), watchlist (pattern, label), emails — reported mail (subject, sender address, sender name), campaigns (name, notes, and the key they were grouped by, so an imphash finds its campaign) and rules (YARA and Sigma by name, yours and the platform's, with platform saying which). % and _ are matched literally.
Inside samples, from three characters: inside lists the files and reported messages whose text contains the query (case-insensitive substring), newest first, each with where it matched — strings, wide strings, document text, macro code, decoded script, imports, exports, rule matches, capabilities, sandbox output, sandbox command lines, sandbox network or message text — and the matching line. The text is every printable string of a file, not the 400 its report shows, up to 1 MB per file. inside.total is how many are listed and more says there were others; nothing counts every match, which would read every matching file to the end.
inside.searched is what makes a miss mean something: how many files this organisation holds (files), how many have their text indexed (files_indexed) and how many only in part (files_in_part — cut at the cap, or a document preview or sandbox log already cut), and the same for messages. A file analysed before contents were indexed is not searched until the operator's backfill reads it. inside.available is false, with the reason, for an organisation that holds its own key and has not switched this on; timed_out says a term matched too much to read in four seconds. A matching file is listed only while your organisation holds it.
curl -G https://app.threatera.eu/api/search \ -H "x-api-key: $THREATERA_KEY" \ --data-urlencode "q=invoice"
{
"query": "invoice",
"detected": "text",
"files": {"total": 2, "results": [ … ]},
"indicators": {"total": 0, "results": []},
"urlscans": {"total": 1, "results": [{"id":"…","url":"…","status":"completed","created_at":"…"}]},
"urls": {…}, "cases": {…}, "watchlist": {…},
"emails": {"total": 1, "results": [{"id":41,"subject":"Invoice 2026-10","from_address":"…","verdict":"suspicious", … }]},
"campaigns": {"total": 0, "results": []},
"rules": {"total": 1, "results": [{"kind":"yara","name":"invoice_dropper","platform":false,"enabled":true}]},
"inside": {"available": true, "total": 1, "more": false,
"searched": {"files": 412, "files_indexed": 398, "files_in_part": 9, "messages": 37, "messages_indexed": 37, "messages_in_part": 0},
"results": [{"kind":"file","hash":"…","filename":"setup.exe","where":"strings","line":"Invoice_%d.pdf.exe"}]},
"total": 6
}URL scans come back in a reduced shape here; fetch GET /urlscans/{id} for the full record.
Whether the contents of your organisation's samples are indexed for search, and how much is. indexed is true unless your organisation holds its own encryption key (own_key) and has not opted in (opted_in); coverage has the same counts as inside.searched, and cap_bytes the text kept per file.
Switch it on or off: {"opted_in": true}. Admins of an organisation that holds its own key only — an analyst gets 403, and an organisation the operator's key protects gets 400, because its contents are always indexed. Switching off deletes what was indexed; switching on indexes files as they are analysed. Returns the same answer as GET, and the change is audited.
Query: kind (sha256, domain or ip) and value. How many other organisations have met a file or indicator you hold. Only where your organisation has opted in (opted_in), counting only organisations that opted in too, and only what each met after it did. Never which organisations, never when: last_30_days and since_opted_in are each a band — fewer than 3, 3–5, 6–10 or more than 10 — so neither an organisation nor “one more since you last looked” can be told apart. Files by SHA-256 and indicators only: never URLs or mail, which can name people.
404 for a value your organisation holds no submission or sighting of: this answers who else met what you met, and is not a lookup over other customers’ holdings. Every one of these rules is enforced inside the database, against the organisation your request is bound to.
{
"kind": "sha256", "opted_in": true, "since": "2026-11-11T09:00:00+00:00",
"last_30_days": { "band": 3, "label": "3–5" },
"since_opted_in": { "band": 6, "label": "6–10" }
}Whether your organisation counts and is counted (opted_in) and since when (since). PUT {"opted_in": true} agrees, admins only, and is audited. Off by default. Agreeing starts the record then — nothing your organisation met before is counted — and withdrawing stops your organisation being counted at once; agreeing again starts afresh.
What the platform can see for your organisation, source by source, over the last 30 days: reported mail, collectors, endpoint protection, uploads by people and the API, URL scans and intel subscriptions. Each has a state — flowing (something arrived), quiet (configured, and nothing arrived, which may be right and is said rather than judged) or off (not set up) — a figure, last_at, a detail and, for a gap, a fix (href, label) naming where to close it. outputs says what happens to it: Autopilot by itself, alert delivery, early warning. gaps counts the sources not flowing. Never a score: how much coverage is enough is yours to judge. Shown on the Dashboard.
Your organisation’s trust report: a vendor security questionnaire answered from the platform’s state now, for procurement and auditors. How samples are encrypted at rest and who holds the top-level key (the operator, or you through your own key service); who has access — members by role, how many have a second factor, disabled members, single sign-on, API keys (send-only, without an expiry, expiring within 30 days) and how many platform operators can open the organisation to support it; the audit trail and whether its chain verifies; retention periods; every connection the platform makes on your behalf with its state here, in the order of the privacy policy’s §12; and what is shared with other organisations. Sub-processors are listed by name, role and location, as Annex III of the DPA has them (the build fails if the two disagree), with whether anything is transferred outside the EU, and the resolver a sample’s DNS goes to on a real-internet run — named though not a sub-processor — with how many such runs your organisation made in 90 days. Hosting is linked to the privacy policy.
GET /api/trust returns report (the data), sections (the same as question/answer pairs) and the notice. GET /api/trust/report?format=pdf (or md) is the document, stamped with when it was generated and recorded in the audit log. Any member may read it; nothing secret is in it. Where the platform cannot observe something it says so — the audit chain’s verification is the platform’s own check, because the chain is keyed.
Every download is issued, and checkable. A fingerprint printed on a document proves nothing on its own — whoever edits the text can leave it alone — so the document ends with Checking it: a link, /trust/check/<token>, that anyone can open signed out and that shows the report exactly as the platform issued it, with the SHA-256 of that text, to compare with the copy in hand. The text is recorded when it is issued; the link’s token is stored only as a hash.
GET /api/trust/reports: the reports your organisation issued, newest first — id, the sha256 of what each said, format, issued_at, issued_by, and withdrawn_at / withdrawn_by. Never the link, which is on the document. Any member.
DELETE /api/trust/reports/{report_id}: withdraw a report’s link — admins only, audited, not undoable. The link then says your organisation withdrew it, and when, instead of showing the report. 404 for a report that is not yours or already withdrawn.
GET /api/trust/check/{token}, signed out: what the link shows — organisation, issued_at, sha256 and body exactly as issued, or only withdrawn_at once withdrawn; 404 for a link never issued. The page a person opens is /trust/check/{token} itself, the same answer as a page; it is not cached, not indexed and sends no referrer, because the token is in its address. 10 a minute per client address.
Were we already hit? Query: kind (sha256, domain, ip or url) and value. Whether your organisation met the value before it was known to be harmful. status is before — with first_contact_at, known_at, what knew (known_by: feed, subscription — one of your own intel subscriptions, by its publisher’s date — analysis or analyst; known_name), the dwell_seconds between them, and the contacts recorded before it was known (at, what, href) — or after, not_known or not_met.
Both moments are recorded, never estimated. Known is the earliest of a feed’s own publication date (not when the platform imported it, and never the Tor exit list, which is not a verdict), the first analysis here that called the file malicious or suspicious, and an analyst’s verdict. Contact is the earliest the organisation recorded the value: its sighting, a file containing it, a reported message, a scanned page, a DNS observation, an endpoint detection, the file itself. Hindsight needs contact at least an hour before knowledge. 404 for a value you have not met.
An hourly job tells new findings — known in the last 7 days, by a feed or this platform’s analysis, never an analyst’s own verdict told back — to owners, admins and analysts, and sends hindsight.found to alert delivery.
Early warning (blind federation): organisations tell each other about the same threat without anybody learning what any one of them holds alone. A value is revealed to the organisations that hold it once three do, and to nobody below that. GET says whether this installation offers it (available), whether your organisation has joined (joined) and since when, the threshold, the window_days a contribution counts for (30) and the kinds of value: sha256, domain, ip — never URLs or mail. PUT {"joined": true} joins, admins only, audited; off by default. Leaving deletes every contribution at once.
What is stored per organisation and value is a token, a point and a share of a secret polynomial, and the value sealed under that secret — none of it readable. The token is a keyed hash whose key lives in a separate service, the blinder, that the platform’s own processes are never given, so the platform cannot make a token for a guess. Three shares of the same value recover the secret; fewer say nothing. Every rule — who counts, the window, that only a holder is told — is enforced inside the database.
For an organisation that blinds its values on its own machine (threatera federate). Body: { "elements": [...] }, up to 500 blinded group elements (512 hex characters each); answered with each raised to the blinder’s key and its public_key, which the client uses to unblind. The platform sees group elements, never a value. Each request spends one of your organisation’s hourly blinding budget (429 when spent), because each blinded value is a guess that could be tested against the threshold. 409 until your organisation has joined; 503 when the installation has not switched federation on.
Body: { "items": [{ "token", "point", "share", "sealed" }] }, up to 500, as threatera federate computes them. Returns how many were accepted and how many of those already have three holders (ready). A value contributed again keeps its first share and counts for another 30 days.
Admins only. Contribute now what your organisation judged harmful in the last 30 days: files the platform or an analyst called malicious or suspicious (an analyst’s false_positive or benign takes a file out), and indicators an analyst judged malicious or suspicious — up to 2,000. An hourly job does the same by itself. Returns values, accepted and ready.
The early warnings: values your organisation contributed that at least three organisations — yours included — hold now, each recovered from the shares: kind, value, the band of holders (3–5, 6–10, more than 10) and when you contributed it. Never which organisations and never when they contributed. With kind and value, only the warning about that value — what a file or indicator page asks. Any member may read them. A new one also notifies your owners, admins and analysts, linking to the value’s page, and is sent to your alert delivery as federation.warning.
{ "warnings": [ { "kind": "domain", "value": "pay-portal-x.com", "band": "3–5",
"contributed_at": "2026-11-14T08:20:00+00:00" } ] }name: null and its key, never with a name made up for it. Cases match on reference, title or summary, and closed cases are included — somebody pasting a hash into search is usually asking "have we looked at this before", and the case that answers it is often a closed one. Watch rules match on their pattern or label, which answers "am I already watching this?" without going to look.Are we affected? Body: { "text" } — an advisory, a CERT's mail or a bare list, up to 512 KB. Every indicator in it is extracted — SHA-256, SHA-1, MD5, domains, addresses, URLs and email addresses, defanged ones included (evil[.]com, hxxps://, user[@]host) — and answered with where this organisation has met it. At most 2,000 values per call; truncated says when more were there.
Evidence kind | Means |
|---|---|
file | A file held here — or, for an MD5 or SHA-1, the analysed file it is the digest of. |
indicator | Recorded here, with how many files, reported messages and sandbox runs carry it. |
dns | One of this organisation's own lookups answered with the address. |
urlscan | The URL was run in the sandbox here. |
email | Somebody here reported mail from the address. |
edr | Your endpoint protection reported the hash — how often and as what, never on which device. |
Returns seen (most recently seen first, each with evidence, first_seen, last_seen) and not_seen, plus extracted and per-type counts. Every value also carries watched and intel — a watchlist rule or a subscription listing it — which are said beside it and are not counted as seen: a subscription listing it is the advisory repeating itself. A value another organisation holds is answered exactly like one nobody holds. Nothing is sent anywhere.
curl -X POST https://app.threatera.eu/api/search/bulk \ -H "x-api-key: $THREATERA_KEY" -H "Content-Type: application/json" \ -d '{"text": "C2: evil-c2[.]example, 185.220.101[.]47"}'
Files
Ingest, look up, analyze, detonate and pivot on file samples. Files are deduplicated by SHA-256.
Upload a file. Stores the raw bytes, records metadata, and indexes it for search.
Form fields (multipart/form-data)
| Field | Type | Description |
|---|---|---|
| file required | binary | The file to upload. |
| scan_type optional | string | quick (ingest only, default) or deep (also queues analysis + a sandboxed detonation). |
| tags optional | string | Comma-separated list, max 5. |
| collector optional | string | The collector sending it, by name: counted on the collector and named on the file. threatera watch sets it. |
curl -X POST https://app.threatera.eu/api/files/upload \ -H "x-api-key: $THREATERA_KEY" \ -F "file=@sample.bin" \ -F "scan_type=deep" \ -F "tags=malware,emotet"
{
"message": "File uploaded successfully",
"filename": "sample.bin",
"queued": ["static_analysis", "detonation"]
}413. So is new material beyond the organisation's storage or daily-upload quota, with an X-Quota-Exceeded header (storage or uploads) and the numbers in the message — but re-submitting a file the organisation already holds is never refused by a quota: it stores nothing new. The SHA-256 of the bytes is the file's identifier — compute it locally to reference the file afterwards.Look up a file's intel record by hash. 404 if never seen.
{
"hash": "8d0a…a255", "filename": "invoice.sh",
"content_type": "application/octet-stream", "size": 200440,
"tags": ["email"], "verdict": "undetected", "yara_matches": [],
"ingested_at": "2026-07-20T08:49:24Z", "last_seen": "2026-07-20T08:49:24Z",
"counter": 1,
"detonation": { "supported": true, "reason": "" },
"provenance": {
"extracted_from": "bebc…8ac9",
"extracted": []
}
}detonation answers "can the sandbox run these bytes?" from the stored object itself, so a client can disable the action before any analysis exists. reason is the server's own wording for why not.
provenance is both directions of the extraction relationship, scoped to your organisation:
| Field | Meaning |
|---|---|
extracted_from | The archive or email these bytes came out of, or null for a direct upload. Set once, on first sighting — a file you later upload yourself keeps the provenance it arrived with. |
extracted | What came out of this file: a zip's members, an email's attachments. Each with hash and filename. |
created_by_run | For a file a sample wrote while being detonated: { "run", "file" } — the run's id and the hash of the file that ran. file is null when retention has deleted the run and kept what it made. null for anything else. |
/api/files/{sha256} lookups. An archive another organisation extracted is not part of the history you see here.Search ingested files, most recently seen first. All filters are optional and combine with AND.
Query parameters
| Param | Type | Description |
|---|---|---|
| hash | string | Full or partial SHA-256; comma-separated for several. |
| tag | string | Exact tag match. |
| content_type | string | Exact content-type match. |
| filename | string | Full-text filename match. |
| verdict | string | One of malicious, suspicious, undetected, unknown. undetected means ClamAV found nothing and no rule matched — never "safe", which no engine can establish; it was called clean until 2026-10-04. unknown also matches files that have never been analysed and so carry no verdict at all — "no engine reached a conclusion" is one question however the gap arose, and the two are told apart on the row itself (unknown against unscanned). |
| decided | string | Whether an analyst has looked — a separate axis from verdict,
which is the machinery's answer. undecided is the queue's own
question: files nobody has judged. decided is any conclusion, and a
named one (confirmed, false_positive,
benign, needs_work) narrows to it — which makes
?decided=false_positive the false-positive corpus.
?verdict=malicious&decided=undecided is the work queue. |
| seen_since | datetime | Only files last seen at/after this ISO time. |
| new_since | datetime | Only files first seen by your organisation at/after this — not seen_since, which a months-old file uploaded again yesterday also matches. |
| sort | string | field:asc or field:desc — one of last_seen, ingested_at, filename, size, content_type, verdict, counter. Anything unrecognised falls back to newest first rather than erroring, so a stale bookmark still returns results. size is held in the index so it can be ordered, while the value shown still comes from Postgres — a document indexed before that field existed therefore reports the right number and sorts last until scripts/rebuild_search_index.py runs. |
| limit / offset | int | Pagination (limit 1–200, default 50). |
curl "https://app.threatera.eu/api/files?tag=malware&seen_since=2026-06-01&limit=20" \ -H "x-api-key: $THREATERA_KEY"
Returns { "total": n, "results": [ FileRecord, … ] }.
The distinct content types actually present in the store, most common first — the valid values for the content_type filter above, so a client can offer a dropdown instead of asking the user to guess a MIME type.
Returns { "content_types": ["application/octet-stream", "text/plain", … ] }.
Download the stored bytes. format=raw (default) is the bare binary, always served as application/octet-stream with an attachment disposition — a stored sample is never rendered or executed inline.
format=zip is a zip holding it, named by its SHA-256, with the password infected — the convention sample exchanges use, so the antivirus on the machine that downloads it does not quarantine it on arrival. The encryption is ZipCrypto (PKWARE's traditional scheme), chosen over AES because the password is public and the point is to keep scanners out, and ZipCrypto opens in 7-Zip, Windows Explorer, macOS Archive Utility, Info-ZIP unzip and Python's zipfile, where AES opens in 7-Zip alone of those. The member is deflated and the archive streamed. 404 for a hash your organisation does not hold, either way.
curl "https://app.threatera.eu/api/files/<sha256>/raw?format=zip" \ -H "x-api-key: $THREATERA_KEY" -o sample.zip unzip -P infected sample.zip
The first 16 KB of a stored file, readable, without analysing it: { "kind", "text", "bytes_shown", "size", "truncated" }, where kind is text (UTF-8 with no NUL), hex (a hex dump of the first 4 KB) or empty. 404 if your organisation holds no such file.
For the files nobody chose to analyse — an archive's members, and the files a sandbox run created — which otherwise show a hash and nothing else, and for an analysed file whose type has no readable preview in its report, which the app shows beneath it. It reads a prefix of the object rather than all of it and interprets nothing; Analyze is still what gives a report.
curl https://app.threatera.eu/api/files/<sha256>/contents \ -H "x-api-key: $THREATERA_KEY"
Record what an analyst concluded about this file. This is a second verdict and it does not touch the first.
verdict on the file record is the machinery's answer — ClamAV,
YARA, capa, the PE classifier, the sandbox — and re-analysis is free to change it. This is a
named person's judgement at a moment, and it has to survive exactly that.
The two are stored and returned separately so a disagreement between them
stays visible instead of one silently overwriting the other.
Body (application/json)
| Field | Type | Description |
|---|---|---|
| verdict | string | null | confirmed · false_positive · benign ·
needs_work, or null to withdraw the decision and
return the file to "nobody has looked". |
| note | string | Why. Required when clearing a file the platform called
malicious — "a person disagreed" is not a record of anything
without the reason, and this is the one direction where being wrong means
a real detection was dismissed. 400 without it. |
curl -X PUT https://app.threatera.eu/api/files/<sha>/verdict \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"verdict":"false_positive","note":"signed internal build, ships with the VPN client"}'
Which verdict should a client use? Where a person is being shown a
conclusion, prefer analyst_verdict when it is set and fall back to
verdict. Anything leaving the platform — a STIX bundle, a
regulatory filing — uses verdict, because it is the reproducible
one and its reader cannot see the note behind a human's. With one exception,
which only ever subtracts: false_positive and benign
withhold the file's indicator from the STIX export, the block list and a
published collection. A person's conclusion can take an instruction to alert
away; it can never add one.
analyst_verdict: null means nobody has looked. It is not a
verdict of unknown, and it is the triage state the Files queue is worked down.
404 if your organisation does not hold the file. Holding it is the question — a hash another customer has analysed is not yours to judge.
The same analyst conclusion about several files. Triage produces this shape of work: a rule fires on forty files from one campaign and every one of them gets the same answer.
| Field | Type | Description |
|---|---|---|
| hashes | string[] | Up to 500 SHA-256 digests. Beyond that this is a filter, not a selection. Any value that is not a hex digest fails the whole request — a typo should not look like a deleted file. |
| verdict | string | null | As the single-file route. |
| note | string | Checked once against the batch. A reason good enough for forty files is a reason; asking for forty is how somebody types "fp" forty times. |
{ "decided": 37, "missing": ["<sha>", "<sha>", "<sha>"] }
It reports what it did, not that it succeeded. decided is
the number of rows actually written and missing names hashes your
organisation does not hold. A caller that selected forty and changed
thirty-seven has to be able to tell — reporting blanket success is how a bulk
control loses somebody's work without either of you noticing.
Queue static analysis (hashes, entropy, type, PE/ELF internals, archive members, Office macros, string & IOC extraction, ClamAV + YARA verdict). Returns 202 with a pending analysis; poll the analysis endpoint.
Body (application/json, optional)
| Field | Type | Description |
|---|---|---|
| archive_password | string | Password to decrypt a protected archive (zip/7z/rar) or an encrypted Office document before analysis. Used for this one analysis and never stored. An encrypted Office document is tried with Excel’s and PowerPoint’s built-in passwords and the short ones lures commonly give before this one; the result’s decryption section says which opened it. |
curl -X POST https://app.threatera.eu/api/files/<sha>/analyze \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"archive_password":"infected"}'
The most recent analysis for a file. 404 if none has run.
{
"status": "completed",
"result": {
"file_type": "pe", "size": 51200, "entropy": 7.91,
"md5": "…", "sha256": "…", "imphash": "…", "tlsh": "…",
"verdict": "malicious",
"detections": { "clamav": {"status":"infected","signature":"Win.Trojan.Emotet"},
"yara": {"status":"ok","matches":["c2_beacon"]} },
"iocs": [{"type":"domain","value":"evil-c2.example.com"}],
"pe": { /* sections, imports, exports, signed, packing… */ }
}
}A PE file gets a pe block; an ELF an elf block; an archive — or a container whose files are read the same way, such as a OneNote section (format: "onenote", its embedded files as embedded-1, embedded-2…) or a disk image (iso, a FAT img raw or partitioned, a fixed or dynamic vhd; paths keep their folders), a cabinet (cab; an LZX folder is listed, not read) or a Windows Installer package (msi: its Binary-table streams, and its embedded cabinets' files by their File-table names) — an archive block (with members; one the image declares longer than the bytes it holds is type: "incomplete" and unhashed, and a format recognised but not read — NTFS, VHDX, UDF-only — has unsupported: true and the reason in parse_error); a macro-enabled Office doc a macros block; a Windows shortcut an lnk block; an installer an msi block; a PDF a pdf block (links with how each is reached, actions with their trigger, forms, embedded_files — also members of its archive block — and qr codes in its page images with images read and not read); an image a qr block (codes, empty when none was found); an HTML or SVG file an html block (forms with method, destination, field count and password, links with how each is reached, and builds_file, download_name and smuggled for a file the page assembles in the browser — each decoded one a member of its archive block); an Office document — OOXML, RTF or legacy OLE — an office block (links it loads or offers, msdt for the Follina shape, dde, xlm with formulas and auto_open, hidden_sheets, and objects with each OLE object's class; a packaged file is a member of its archive block). An RTF is sniffed as rtf. A .NET executable adds a dotnet block beside its pe one (assembly, version, runtime, references, il_only, obfuscators named by their marker, resources with size, sniffed type and entropy — one that is itself a file is a member of its archive block — and the urls in its string literals, which are not URL indicators). A PE or ELF built by PyInstaller adds a pyinstaller block (python, entry_points — each a .pyc member of its archive block — bootstrap, binaries, encrypted_modules). A Windows batch file (type batch, not detonated) adds a batch block: runs, the commands as cmd would expand them, with changed, variables and unresolved. An .xlsb (type xlsb) adds xlm.strings, the text inside its binary formulas. A PDF's or a page's web links and every QR code's are also URL indicators, recorded as “a link in a document” and “opened by a QR code”.
An installer is read for what it runs. msi.custom_actions decodes the CustomAction table: per action its action name, type and kind (“EXE named by a property”, “inline VBScript”…), whether it runs something, its source and target — the command line or the script itself — and whether it is deferred and runs as_system. The targets of the actions that run are read like a shortcut's: URLs in them become indicators, and an encoded PowerShell command becomes a layers entry.
A shortcut is read for what it would run. lnk.command_line is the target and the arguments as Windows would see them; target_source says which of the shortcut's four places named the target (link info, environment block, target ID list, relative path), and targets lists them all when they disagree — how a shortcut shows one thing and runs another. Also working_dir, icon_location, show_command (minimised hides the console), name and machine_id. URLs in the arguments become indicators, and an encoded PowerShell command in them is decoded as a layers entry. Shortcuts are not detonated.
A PE is also scored by a model, offline. ml is EMBER2024’s PE classifier run on the file’s bytes with nothing sent anywhere: state (pending while it runs after the rest of the analysis, done, not_assessed for anything that is not a PE or is over 16 MB, unavailable with a reason), and when done score (0–1), band (likely_malicious, uncertain, likely_benign), threshold, model, model_source, model_sha256 and drivers — the feature groups that moved the score most, in log-odds. A score at or above threshold raises an unknown or undetected verdict to suspicious; it never lowers a verdict, never reaches malicious and never clears one. band describes the score and is not a verdict: benign software built like malware scores high too.
Queue dynamic detonation — actually execute the sample in a locked-down, throwaway container and capture behavior. Returns 202. If the file type isn't supported, the record comes back status: "unsupported" with an error and nothing is queued.
Two backends, chosen from the file's own bytes and reported on the record as backend:
| Backend | Runs | How |
|---|---|---|
linux_container | ELF binaries, shell and shebang scripts | Executed directly in the container. |
powershell_core | PowerShell scripts (.ps1) | Executed under PowerShell 7 on Linux — see the note below for what that does and does not observe. |
windows_wine | Windows PE executables (32- and 64-bit); JScript and VBScript | Executed under Wine — scripts under Wine's own cscript. Reports Windows paths, and diffs the registry value by value so a Run key or a service install shows up as a finding rather than as "user.reg was modified". |
calc.exe, cmd.exe and whoami are absent; and no WMI or COM. A script depending on those reports errors for them and carries on, and the persistence section names the ground that could not be covered rather than reporting its absence as a finding. A quiet run is not a clean verdict.This backend exists because the alternative was silence: a
.ps1 has no magic number and no shebang, so it sniffed as plain text, and the shell-script heuristic matched on if, for, function and $( — all of which PowerShell shares with sh. The script was handed to /bin/sh, which died on its first line, and the run was reported as completed with an empty process tree. Nothing on screen distinguished "this sample does nothing" from "this sample was never executed".responseBody is not implemented and ADODB.Stream cannot be called — so a dropper stops after its request, which is still captured; and VBScript cannot create MSXML objects at all (WinHttp works). A .wsf is refused: nothing runs from one. An archive member that is a script must end in .js or .vbs, because the script host chooses its language by extension.windows_wine run carries a fidelity object saying exactly this, so the caveat travels with the report rather than living only here. HTTPS request bodies are also not decrypted for Windows samples (Wine has its own certificate store, which the sinkhole's throwaway CA is not in); the hostname is still captured from the DNS query and the TLS handshake.Query parameters
| Param | Values | Description |
|---|---|---|
| network | sinkhole · none · egress | Network containment. sinkhole (default) — fake internet, records what the sample tried to reach, nothing leaves the host. none — no network. egress — real internet access (opt-in; the sample can reach the outside world). Note that a sinkholed sandbox has no route off its isolated bridge: hostnames resolve to the fake server and are recorded, but traffic addressed straight to an IP (ping 8.8.8.8) fails with Network is unreachable and never reaches the wire, so it cannot be reported. Use egress to observe that. |
| trace | true · false | Windows samples only. Records the API calls the sample makes — what it asked the system to do, rather than only what it left behind. This is what catches the sample that injects into another process, or resolves its functions by name at run time, and never touches disk: both leave an empty filesystem and registry diff. Off by default, and ignored on a Linux run rather than promising a trace the report cannot contain. Two costs. The run is slower, so raise the timeout for a sample that was already close to it. And Wine's relay layer is observable from inside the sandbox — a sample that looks can tell it is being traced, and may behave differently for that reason alone. |
| syscall_trace | true · false | Linux samples only. Records every process the sample starts, under an strace -f, including ones too short-lived for the process poller (which samples /proc every 50 ms, so a curl that lives milliseconds can run, reach the network and leave no process in the tree — and no Sigma rule on its command line can fire). Off by default (DETONATION_SYSCALL_TRACE_DEFAULT) because it ptrace-attaches the sample: the sample is no longer PID 1 and ptrace(PTRACE_TRACEME) — a standard anti-debug check — tells an evasive sample it is watched, so the completed run's fidelity note says so. The network and dropped files are unchanged either way (the pcap records the first, the filesystem diff the second) — except with network=none, where no capture runs: there the trace also records each routable address the sample tried to connect to (network.attempted), and counts its attempts to look names up (network.lookups_attempted) without naming them, since which name was asked for cannot be seen without a network. Ignored on the Wine and PowerShell backends, which have their own tracing. |
| memory_capture | true · false | Linux samples only. Starts the sample under the memory reader, which reads what it unpacked — 20 seconds in and at the deadline — and keeps each program it finds (ELF or Windows) as a file of yours, decoded and matched by your YARA rules, as every Windows run already is. Off by default: the sample is then not PID 1 and its parent is the reader, which a sample can check, and the run’s fidelity note says so. Ignored on the PowerShell backend. |
| timeout_seconds | integer | Run for longer than the default, up to the installation’s ceiling (DETONATION_MAX_TIMEOUT_SECONDS, 180 by default) — for a sample that sleeps past the default and reads as one that does nothing. Stored on the run. 400 outside that range. |
| args | string | Command line passed to the sample, shell-quoted — --verbose -c /tmp/cfg. Parsed like a shell, so an argument containing spaces has to be quoted. Many droppers do nothing at all without the flag their loader passes them, and detonating one bare produces a clean report about a sample that never ran. The arguments used are echoed back on the detonation record. |
| entry_point | string | Archives only, and required for them. Which member to run, with every other member laid out beside it — the name from GET /files/{hash}/archive-members. Which file runs is your decision; the platform will not guess, so detonating an archive without it is refused. |
| export | string | DLLs only, and required for them. A DLL is a library, not a program: the sandbox loads it with rundll32 (running its DllMain) and calls this export — a name or #<ordinal> from GET /files/{hash}/dll-exports, or * to load it and call nothing. Refused for anything that is not a DLL. With entry_point, it is that archive member's export. |
curl -X POST "https://app.threatera.eu/api/files/<sha>/detonate?network=sinkhole" \ -H "x-api-key: $THREATERA_KEY"
What an API trace reports
Not the raw firehose. A full relay trace is millions of lines and a slowdown of one to two orders of magnitude, so the trace is scoped at the source to a curated set of functions — file, registry, process, network, crypto, service, loader and anti-analysis. The result carries three things: counts per category, the named behaviours that no single call demonstrates (process injection is WriteProcessMemory and CreateRemoteThread; either alone is ordinary), and the calls themselves with their string arguments — the path written, the URL fetched, the value set.
api_trace.status is ok, quiet (the trace ran and the sample called none of the watched functions — an observation, not a fault), empty (the harness failed, with the lines it did get) or unsupported, each with a reason — because "the harness failed" and "the sample was quiet" look identical otherwise, and only one of them is a finding.export was used, api_trace.dll_load reports what Wine's loader did with the library: loaded, what its DllMain returned (dllmain_returned), any missing dependency, and a one-line summary. A library that never loaded ran none of its code, so every empty section of that report means not run, not did nothing. It is read from the trace, so it needs trace on.The run's packet capture, as a pcap file — open it in Wireshark, replay it through Suricata or Zeek, keep it as evidence on a case.
These are the bytes tcpdump wrote, unmodified. The network summary on the detonation report is read back out of this same file rather than captured separately, so the download and the report cannot disagree about what crossed the wire.
curl "https://app.threatera.eu/api/detonations/42/pcap" \ -H "x-api-key: $THREATERA_KEY" -o run-42.pcap
404 when the run captured nothing: network=none, a run that failed before the capture started, or any detonation from before captures were kept. Very chatty samples stop at 100,000 packets — the file stays a valid capture, and the report says when the limit was reached.
Your other sandbox runs that behaved like this one — compared on what each run did, not on any hash. Files dropped where, registry keys written, processes started, the kind of host reached, the API categories and named behaviours seen: a repacked or renamed build of the same thing matches here although it shares no SHA‑256 and perhaps no indicator.
Each match carries a similarity (0 to 1 — shared behaviour over combined) and the shared features behind it, and compared says how many of your runs were looked at. A run from before the behaviour profile was recorded carries none and comes back status: "no_genome" with the reason, rather than an empty list that would read as "nothing is alike".
curl "https://app.threatera.eu/api/detonations/42/behaves-like" \ -H "x-api-key: $THREATERA_KEY"
{
"status": "ok", "compared": 412,
"matches": [
{ "detonation_id": 39, "similarity": 0.84,
"verdict": "malicious", "filename": "invoice.scr",
"shared": ["drop:exec@roaming", "reg:run-key", "net:tls"] }
]
}404 if the run is not one of yours. Scoped to your organisation's own runs throughout; nothing another customer detonated is ever compared or named.
Sigma rules drafted from what one completed run did, tested on your other runs before they are offered. One rule per kind of event the sample produced — names it looked up, routable addresses it connected to, request lines, executables it dropped (by where they landed, without the user name), Run and service keys, persistence, programs it started — each 1 of selection_*. The sandbox’s own doing is never a candidate: not the sample’s own process, not an address in a sinkholed run, not the resolver, not a system program every sample starts.
Each candidate is run against up to corpus of your most recent other runs (default 300, at most 1000). One that matches a run of a file an analyst marked benign or a false positive is dropped, as is one matching runs of more than a fifth of the files compared. Every candidate comes back in candidates with why it was chosen and, if dropped, why. Each rule carries matches_run and the other runs it matched. With nothing left, rules is empty and refused says why. Nothing is saved: save a rule with POST /api/sigma-rules.
curl -X POST "https://app.threatera.eu/api/detonations/42/sigma-draft" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" -d '{"corpus": 300}'
{
"detonation_id": 42, "corpus": { "runs": 118, "files": 20 },
"rules": [
{ "name": "threatera_invoice_9b460227_dns_query", "category": "dns_query",
"matches_run": true, "also_matches_total": 1,
"source": "title: 'invoice.scr: names it looked up'\n..." }
],
"candidates": [
{ "field": "QueryName", "value": "c2.example-c2.net",
"in_files": 0, "kept": true, "dropped": null }
],
"refused": null
}404 if the run is not one of yours. Only your organisation’s runs are compared or named.
What is inside a stored archive, and which members could be detonated. Use it to choose an entry_point for POST /files/{hash}/detonate.
One file per run misses the samples that need their siblings — a signed executable beside the DLL it side‑loads does nothing interesting on its own, and a script that reads a config from its own folder fails without it. Naming a member runs that member with the whole archive laid out around it.
{
"hash": "9f2b…",
"members": [
{ "name": "app.exe", "size": 184320,
"detonable": true, "backend": "windows_wine", "reason": "" },
{ "name": "version.dll", "size": 51200,
"detonable": false, "backend": null,
"reason": "The sandbox cannot execute 'unknown' files…" },
{ "name": "data/config.ini", "size": 82,
"detonable": false, "backend": null, "reason": "This is a text file, but…" }
],
"truncated": false
}detonable is answered per member by the same check the detonation itself uses, so the list cannot offer something the run would then refuse. backend follows the member, not the archive: the same zip runs under Wine when you pick a PE and on Linux when you pick a shell script.
Names are normalised the way the sandbox will normalise them, and an archive with an absolute or traversing path (../) is rejected outright with 400 — it is refused for the whole archive rather than skipped, because a member trying to write outside its own directory is a property of the archive worth knowing.
400 if the file is not an archive, or expands past the sandbox’s limits (512 members, 256 MB uncompressed). 404 if the file is unknown. Listing stops at 200 members with truncated: true.
Which exports of a DLL a detonation can call. A DLL is a library, not a program — it does not run on its own — so the sandbox loads it with rundll32 (its start‑up code, DllMain, runs) and then calls one export you name on POST /files/{hash}/detonate as export.
{
"hash": "9f2b…",
"exports": ["Install", "ServiceMain", "#3"],
"load_only": "*",
"entry_point": null
}Each entry is an export as rundll32 will be told it: a name, or #<ordinal> for one exported without a name. Pass one as export, or "*" (the load_only value) to load the DLL and call nothing. The names are read from the stored bytes by the same check the detonation uses, so the picker cannot offer one the run would refuse.
exports is null when the file is not a DLL, and [] for a DLL that exports nothing — which can still be loaded. Pass entry_point to ask the same question of one member of an archive.
400 if an entry_point is given that is not in the archive. 404 if the file is unknown.
The most recent detonation run for a file. 404 if none has run.
{
"status": "completed", "backend": "linux_container", "network_mode": "sinkhole",
"result": {
"exit_code": 0, "timed_out": false, "duration_seconds": 0.42,
"stdout": "…", "dropped_files": [{"path":"/tmp/x","kind":"added"}],
"network": { "mode":"sinkhole", "dns_queries":["evil-c2.example.com"], "ports":[80] },
"iocs": [{"type":"domain","value":"evil-c2.example.com"}]
}
}A windows_wine run carries two more keys in result:
{
"status": "completed", "backend": "windows_wine",
"result": {
"dropped_files": [{"path":"C:\\users\\nobody\\Temp\\evil.exe","kind":"added"}],
"registry_changes": [{
"key": "HKEY_CURRENT_USER\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\\Updater",
"kind": "added", "value": "C:\\users\\nobody\\Temp\\evil.exe"
}],
"persistence": [{"mechanism":"registry-run", "description":"a Run key, which starts …"}],
"fidelity": { "emulated": true, "note": "Run under Wine, not Windows. …" }
}
}registry_changes is a value-level diff against a pristine copy of the hives baked into the sandbox image — Wine rewrites all three hive files on every shutdown regardless of what happened, so a file-level comparison would report the whole registry as modified on every run. Per-machine identity that Wine rebuilds each start (computer name, Tcpip\Parameters\Hostname, volatile environment, driver timestamps) is excluded: it is the harness's, not the sample's.
network.tls is every TLS connection the sample made, fingerprinted from the run's capture: the server and sni, the client's JA4 and JA3 (with ja3_string), the server's JA3S, and cert_sha256 where the handshake shows the certificate (TLS 1.2 and older). A TLS client survives a rebuild that changes every hash. Only JA4 of the JA4+ family: the others are licensed for non-commercial use. GET /api/tls-fingerprints/runs with ?ja4=… (or ?ja3=…, exactly one) lists your runs in which a sample spoke with that client, newest first — detonation_id, file_hash, filename, completed_at and the servers it reached with it; 400 for a value that is not a fingerprint.
network.http_clients is every distinct plain-HTTP client the sample asked with, read from the capture: a fingerprint of its own (h_, the method and version, the number of headers and the first twelve hex digits of the SHA-256 of the header names as sent — in order, case kept), the headers, the user_agent (beside it, never in it), the servers and how many requests. The platform’s own fingerprint, not JA4H, whose licence is non-commercial. Plain HTTP only: HTTPS requests are encrypted in the capture. GET /api/http-fingerprints/runs with ?fingerprint=… lists your runs that asked with that client, as the TLS lookup does; 400 for a value that is not one.
network.beacons is every server the sample called on a schedule, read from the capture’s timing: the server, port and name (the TLS server name, when exactly one was used for that address), how many contacts, every_seconds (the median interval), shortest_seconds and longest_seconds, jitter_percent and over_seconds. A contact is a new connection or data sent on one kept open; a schedule is at least four contacts, every interval a second or more, the shortest at least half the longest. Where a decoded configuration names a sleep, config gives its family, sleep_seconds, jitter_percent and whether the traffic fits it. Empty when nothing kept a schedule, which a beacon sleeping longer than a quarter of the run cannot.
quiet is set on a completed run that did nothing visible — no file written, nothing persisted, no registry value, no network, no other process, nothing the API trace classifies — and is null on any run with findings. Its reasons each carry what was said and the evidence it rests on: still running at its limit; it slept, checked for a debugger or looked for Wine (from the API trace); a program or library it needed is not in the sandbox (the shell’s 127, the loader’s message); a Windows loader failure, as the low byte of its status (53 for STATUS_DLL_NOT_FOUND, said as “most likely”); usage text asking for arguments; exited at once; a script stopped on an error. With no visible cause it says that, not a guess. next lists the runs that could tell more, each with the params to start it: longer (timeout_seconds, only when there is longer to give), without the API trace (only when it had one), or with arguments. timeout_seconds is the run’s own budget when it was given longer.
memory (Windows runs) is what the sample unpacked in memory: the payload a packed sample decrypts only while it runs, which the file on disk never shows. Its memory is read 20 seconds in and again at the deadline, and every Windows program image in memory not backed by a file is carved out — held in a buffer (layout: "file"), laid out to run ("mapped", realigned so it reads as a file), or the sample's own image rewritten in place ("self"). Each entry in images has the process and address it was found at, size, sha256, a decoded config when a decoder recognised it, the yara rules of yours it matched, and "stored": true once it is a file of yours, openable under /api/files/{sha256} (its decoded C2 hosts become indicators of that file). rounds says which looks completed, unreadable names any process whose memory could not be read and why, and cut is true where a limit stopped the search — so an empty list says whether nothing was there or nothing could be looked at. null when memory was not read.
dropped_files carries the file's sha256, size and a preview of its first 4 KB. Up to 25 files of 1 MB each, and 8 MB across the run, also come back whole and are stored like an archive's members — encrypted, held by your organisation, and openable under /api/files/{sha256}, where provenance.created_by_run names this run. Those entries carry "stored": true; one over the run's limit carries content_not_returned with the reason, and keeps its preview. Nothing stored this way is analysed or detonated automatically — a file a sample wrote waits for you to press Analyze, for the same reason an archive's members do.Indicators extracted from this file (the file → IOC pivot), each with type, value and first_seen — when your organisation first met the indicator. 404 if the file is unknown; an empty list if it has no indicators.
Files related to this one by TLSH fuzzy-hash distance and imphash. Optional query params: threshold (max TLSH distance, lower = stricter) and limit (how many fingerprinted files the TLSH comparison reads, newest first; default 500).
Imphash matches come from your organisation's whole corpus, by exact lookup. TLSH has to be compared pair by pair, so it reads the limit most recently added fingerprinted files; the response headers X-Similarity-Compared and X-Similarity-Corpus say how many that was, out of how many there are — an empty list over part of the corpus is not the same answer as one over all of it.
Draft a YARA rule from the file’s code rather than its strings. A C2 path or a mutex is what the next build changes; the routines are what it keeps. The rule pins the file’s largest distinctive functions that at least one related file also contains (never a compiler’s runtime, which more than a fifth of your files carry), each as a hex pattern of its opening bytes with every address, branch target and large constant wildcarded — or for .NET its IL with the metadata tokens wildcarded — and needs most of them to match.
Tested as the string draft is: each pattern over up to corpus of your stored files (body {"corpus": 500}), dropped if it is in a file an analyst marked benign or a false positive or in more than a fifth of them. test says whether the rule matches this file, how many of its relatives it matches, and what else; every routine in functions carries what it calls and why it was kept or dropped. With fewer than two patterns it refuses with the reason. Nothing is saved. 404 if your organisation does not hold the file.
Which of up to 500 SHA-256s ({"hashes": […]}) your organisation already holds, in held — what a collector asks before sending, so a known file costs no upload. It answers about your holdings only; whether anybody else holds a file is never said.
A collector checking in: name (one per collector, created on first contact), kind, host, the folder it is watching, its version and interval in seconds, how many files it found already held since it last checked in, and its last error. threatera watch sends it every interval. Requires write access. The answer carries paused — when true, send nothing until it is false again — and the latest_version of threatera.py this platform serves; threatera watch obeys the first and mentions the second.
Your collectors — folders on your side that send their files in by themselves (threatera watch). Each with what it watches and from which host, its version, when it last checked in and its status: active, silent (three intervals without a check-in — a collector that died looks exactly like one with nothing to send) or never — a collector that goes silent is told to the organisation’s owners and admins as a notification and to its alert delivery as collector.silent, once per silence; files_sent, messages_sent (mail sent to the mail analysis, kind mail when it sends everything that way), files_held (found but already held, so not sent), last_file_at and last_error. A file a collector sent names it (upload field collector). The platform connects to nothing of yours: a collector connects in, with an API key — best a send-only one (POST /api/api-keys with "scope": "collector"), which can call files/held, files/upload, email/messages (to send) and collectors/heartbeat and nothing else, under its own name only (403 collector_key_send_only otherwise). Also paused_at and paused_by when an admin paused it, arrivals — what arrived on each of the last 14 days, oldest first, a day with nothing as 0 — and outdated, running an older threatera.py than this platform serves.
Pause or resume a collector from the platform (admins), audited. A paused collector is told at its next check-in to send nothing, and whatever it sends meanwhile is answered 503 collector_paused with Retry-After — try again later, never a refusal — so a file that arrives while it is paused is sent once it is resumed, by any version of the CLI. 404 if it is not yours.
Forget a collector (admins). Its files stay, still naming it; one still running reappears at its next check-in — stop it, or revoke its key. Recorded in the audit log. 404 if it is not yours.
Autopilot: the platform works the investigation of one of your files, or one of your reported messages, through by itself. Body {"kind": "file", "ref": "<sha256>"}, {"kind": "email", "ref": "<message id>"} or {"kind": "ioc", "ref": "<domain, IP or URL>"} (one your organisation has met); returns the investigation (or the one already running on it). For an indicator it reads what it is (local GeoIP and ASN, the feeds and intel subscriptions listing it), where it appears here, the DNS already observed (no lookup is made) and what else shares those addresses, its files' campaigns and who they reached. For a message it reads what the message itself gives away, investigates each attachment as a file (up to 5) and waits for them, renders each link in the URL sandbox (up to 5) and checks the page for a password form and for copying a page you marked as yours, finds the campaign it resembles and the other reports of the same wave (sender domain, attachment or link host, last 14 days). For a file: It queues a static analysis if there is none and a sinkholed sandbox run if the type can run — never with real internet, within your sandbox budget — waits for both, then reads relatives and campaign, who it reached, rare infrastructure, drafts and tests detection rules (saving none), writes the cited write-up and lists the decisions left for you. It records no verdict, opens no case, starts no reporting clock and adds no watch rule. Requires write access. 404 if your organisation does not hold the file.
Your Autopilot investigations, newest first: the file (subject_ref, filename), what started it (trigger: manual, reported_mail or edr, and trigger_ref, the message or detection), status (queued, running, waiting, done) and, once done, the verdict its analysis reached. ref narrows to one file, active=true to those still running; limit up to 100.
Whether Autopilot starts by itself for your organisation: on each reported message, investigated whole — its attachments and links included (on_mail) — and on each file your endpoint protection flags that you hold (on_edr). Both off by default; PUT {"on_mail": true, "on_edr": false} changes them (admins; recorded in the audit log). Each investigation uses your sandbox budget. A message of the same wave (the same sender domain and subject) as one investigated in the last 24 hours is answered by that investigation, a file investigated in the last 24 hours is not started again, and at most 10 automatic investigations run at once; beyond that the rest wait for the button on their page. A detection of a file you do not hold starts nothing: Autopilot works on the file.
Open a case from a finished investigation — a person's decision, made with one call. Body {"title": "…", "severity": "high"}, both optional (the title defaults from the verdict and subject, severity to medium). The case holds the file or message investigated; for a message, the attachments judged harmful and the rendered pages that asked for a password or copied a page of yours; for a malicious or suspicious file, up to five of its rare indicators — only what your organisation holds. Its summary is the cited write-up, marked as Autopilot's, and its timeline shows each Autopilot step as a line the platform recorded, at the time the step finished. No reporting clock starts. Returns case_id, reference, items and not_held. 409 if a case was already opened from it, 400 while it runs, 404 if it is not yours.
The latest investigation of each file or message named — repeat ref (a sha256 or a message id, up to 100) — keyed file:<sha256> or email:<id>, each with id, status, the verdict once done and finished_at. What the Inbox reads to mark an item "dossier ready"; one not investigated is absent.
A finished dossier as a document: format=md (default) to paste into a ticket, format=pdf to send. The same facts, summary, decisions, drafted rules, cited write-up and step record as the page, rendered from the stored investigation, opening with a line that Autopilot wrote it and decided nothing. Citations keep the platform's own paths. 400 while it runs, 404 if it is not yours.
One investigation as it stands — poll it while it runs. steps in order, each with status (pending, running, waiting, done, skipped, failed), started_at, finished_at, a one-line summary, its facts and the cites that show them. Once done, dossier: verdict, campaign, devices and people reached, rare_indicators, the drafted rules (tested, unsaved), the cited writeup, the decisions left for you and the seconds it took — composed only from the steps. 404 if it is not your organisation's.
Every byte of the file, drawn, and what each part is — the data behind “See its anatomy”. The file is laid along a Hilbert curve, which keeps neighbouring bytes together, as side×side cells, each a contiguous run of the file. cells is base64, two bytes per cell: zero << 4 | control, then text << 4 | high, each the share of that cell’s bytes out of 15 (0xFF is what remains). entropy is base64, one byte per block (0–255 for 0–8 bits per byte), each block a power-of-four square of cells and never under 1 KB.
regions names what can be named: what the file’s own PE or ELF headers say (header, section with executable and writable, overlay — data after the last section), a signature where another file appears to begin (a Windows program counts only with a PE header where it points), and dense runs of at least 4 KB at 7.2 bits or more — compressed or encrypted, which the bytes cannot tell apart. For a Windows program, code.routines says where each routine begins (at, a file offset; its extent is not given, because code reached by a walk is not one range), its instructions, up to four calls, how many of your other files hold it (elsewhere) and its kind: only_here, shared or library (code more than a fifth of your files carry). Files over 32 MB are not read (status: "too_large"); any other status carries its reason. Nothing is stored. 404 if your organisation does not hold the file.
Up to 512 bytes from one place in the file, for the anatomy’s hex view: query offset (default 0) and length (1–512, default 256). bytes is base64; within the first 32 MB, past which bytes is empty with a reason. 404 if your organisation does not hold the file.
The file’s family as your organisation has met it. nodes: every related build — gathered two steps out through shared code, at most 24 — in the order you first met them, each with its verdict and self for this file. edges: each build descended from the earlier build it shares the most distinctive functions with (a compiler’s runtime set aside), with the functions added and removed and up to three new_calls — APIs it calls that its parent called nowhere. A build sharing too little with every earlier one starts its own branch. Ordered by arrival, which is not proven build order. 404 if your organisation does not hold the file.
What this build changed against an earlier relative. Query against names the file to compare with; without it, the file this one shares the most distinctive code with among those your organisation met earlier (chosen: "nearest"), or status: "no_relative" with the reason.
Layer by layer: functions added and removed, each with what it calls — imported functions for native code, resolved through the import table and the compiler’s thunks; members called from outside the program for .NET — and new_calls, what only the new build calls; imports added and removed; a decoded config’s changed fields; indicators gained and lost; behaviour the sandbox saw start or stop; build — claimed build time, signature and packing changes. A layer either file cannot speak to says known: false rather than reading as unchanged. 404 unless your organisation holds both files.
A first write-up of the file, assembled from what the platform concludes about it — with no language model. Each sentence is a template filled from one finding and carries cites, the page that shows it: the verdict and what it rests on, the static findings that matter, what the sandbox saw, the runs that behaved alike, the campaign, shared code, rare indicators, and the devices and people it reached. What is not known is said — never run in the sandbox (or why it cannot be), no endpoint protection connected, an older analyser, capability analysis still running — rather than left out.
sections holds the sentences, next_steps what follows from the same facts (record a verdict, run it, watch its rare indicators), and text the whole of it as text with numbered sources, to paste into a ticket. Nothing is stored. 404 if your organisation does not hold the file.
Which malware family the file is, and every piece of evidence that says so. Each item has a rank: decoded — a configuration decoded from the file, a decoded script layer or a sandbox run’s memory; named — a ClamAV signature or YARA rule whose name carries a family; resembles — shared code with, or a TLS client fingerprint (JA4) or plain-HTTP client used only by, your own files that are decoded or named, with those files.
status: "called" gives the family and a confidence: confirmed on a decode, likely when two kinds of evidence agree, otherwise possible; against lists weaker evidence for other families, and related says when a fork (DcRAT, VenomRAT) agrees with the family it was built from. status: "disagree" when two families have evidence of the same rank: no family is called, and each is in candidates with its evidence. status: "none" means nothing named a family, not that the file is harmless. Computed when asked, from your own analysis, runs and files; nothing is stored.
{
"status": "called", "family": "DcRAT", "confidence": "confirmed", "rank": "decoded",
"evidence": [
{ "family": "DcRAT", "rank": "decoded", "kind": "config",
"says": "its DcRAT configuration was decoded from the file" },
{ "family": "AsyncRAT", "rank": "named", "kind": "rule",
"says": "YARA rule Windows_Trojan_AsyncRat_11a11ba1" }
],
"against": [], "related": "DcRAT is built from AsyncRAT's source, so what names AsyncRAT agrees"
}404 if your organisation does not hold the file.
Draft a YARA rule from this file, tested against your own stored files before it is offered. A hash stops one build; a rule over what the operator wrote — the C2 path, the mutex, the PDB path, the ransom note — catches the next one too.
Candidates are the sample's most specific strings, narrow and UTF-16, each with the reason it was chosen. What every binary carries — the DOS stub, DLL, API and section names, compiler and language-runtime messages — is never a candidate. Each candidate is looked for in up to corpus of your most recently seen files (body {"corpus": 500}, at most 1000) and dropped if it is in a file an analyst here marked benign or false_positive, or in more than a fifth of them. The platform's undetected verdict is not used to drop anything: that is what a sample nothing has a signature for looks like.
The assembled rule is run over the sample and every file that held one of its strings: test.matches_sample and test.also_matches (with each file's verdicts) are observations. With fewer than two strings left the draft refuses — source is null and refused says why, usually that the file is packed, with its entropy. Nothing is saved; save it with POST /api/yara-rules. A saved rule that matches makes a file suspicious on re-analysis, which is how an undetected sample reaches a case's block list. 404 if your organisation does not hold the file.
A single shareable report for a file — the intel record, detections, static analysis, extracted indicators and the sandbox detonation bundled into one document. This is the thing you attach to a ticket instead of screenshotting five panels.
Query parameters
| Name | Type | Description |
|---|---|---|
| format | string | md (default) for Markdown, pdf for a laid-out PDF. |
Responds with text/markdown or application/pdf as a download (Content-Disposition: attachment), not JSON. 404 if the file is unknown.
curl -O -J "https://app.threatera.eu/api/files/8d0a…a255/report?format=pdf" \ -H "x-api-key: $THREATERA_KEY"
/analysis first if you need them populated.Indicators (IOCs)
IPs and domains, deduplicated with a sightings model and linked to the files and scans that touched them. Single-indicator lookups are enriched with offline GeoIP/ASN data.
Submit an indicator (type auto-detected). Re-submitting bumps the counter and refreshes last_seen. Non-routable / internal values are rejected with 400.
Body (application/json)
| Field | Type | Description |
|---|---|---|
| value required | string | A valid IP address or domain. |
| tags | string[] | Up to 5 tags. |
curl -X POST https://app.threatera.eu/api/iocs \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"value":"185.220.101.1","tags":["c2","tor"]}'
Search indicators, most recently seen first. Filters combine with AND.
Query parameters
| Param | Type | Description |
|---|---|---|
| type | string | ip or domain. |
| tag | string | Exact tag match. |
| value | string | Value prefix match. |
| seen_since | datetime | Only indicators last seen at/after this. |
| new_since | datetime | Only indicators your organisation first encountered at/after this — what the dashboard's week counts. |
| decided | string | What an analyst here concluded: undecided (nobody has), decided (anybody has), or malicious, suspicious, benign. Anything else is a 400 rather than an ignored filter. Each result carries analyst_verdict when somebody has decided. |
| sort | string | field:asc or field:desc — one of last_seen, first_seen, value, counter, type, tags. An indicator carries several tags, so tags orders by the alphabetically first one — in both directions, which is what makes descending the exact reverse of ascending. Case is ignored, so Spam sits with spam rather than ahead of every lowercase tag. |
| limit / offset | int | Pagination. |
Look up a single indicator (type inferred). 404 if unseen.
{
"type": "ip", "value": "185.220.101.1", "tags": ["c2","tor"],
"first_seen": "…", "last_seen": "…", "counter": 5,
"enrichment": {
"network": {
"asn": 60729, "as_org": "Stiftung Erneuerbare Freiheit",
"country": "DE", "country_name": "Germany" },
"feeds": [{
"feed": "tor_exit", "name": "Tor exit nodes", "label": "tor exit node",
"confidence": null, "reference": "https://…", "first_seen": "…" }],
"intel": [{
"source": "CERT-AT feed", "kind": "taxii", "label": "Emotet C2",
"confidence": 80, "tlp": "amber", "reference": "indicator--…",
"first_seen": "…" }]
}
}The enrichment blocks
Every one of them is answered locally. GeoIP reads a bundled database, feed and intel matches read tables this deployment already downloaded on a schedule. Nothing here asks a third party anything at lookup time, which is the whole point: opening an indicator is not audible to whoever runs the source. Absent blocks are omitted rather than sent empty, and enrichment itself is absent when there is nothing to add.
| Key | Present for | What it is |
|---|---|---|
network | IPs | Offline GeoIP/ASN — asn, as_org, country, country_name. |
feeds | either | The public threat feeds that list this value. Identical for every organisation on the installation. |
intel | either | Your organisation's own TAXII/MISP subscriptions. Tenant-scoped, and each entry carries the tlp it arrived under. |
feeds and intel are deliberately not merged. Both answer "is this known bad?", but only one answers it with a source the customer chose and is accountable to, and only one carries a marking that limits what may be done with the answer. Flattening them would lose both facts at the moment an analyst is deciding whether to act. Neither is a sighting: counter, first_seen and last_seen stay what your organisation encountered.Keep an address or domain on your organisation's block lists however long it goes unseen — a C2 domain an actor keeps returning to. DELETE the same path to let it expire like any other value. 404 if your organisation has never encountered it. Every indicator record carries pinned and pinned_by, and expired. Audited.
Remove the pin; the value expires again on your organisation's period.
After how many days without a sighting an address or domain leaves your cases' block-list exports: {"days": 30}, or {"days": null} for never — the default. Addresses are recycled; the one a campaign used two years ago is somebody's mail server now. Nothing is deleted: an expired indicator stays searchable, every listing marks it expired, and the block list withholds it with the date it was last seen. File hashes and URLs never expire.
Set the period, admins only: {"days": 1–3650}, or {"days": null} for never. Audited.
Record what an analyst here concluded about an indicator: malicious, suspicious or benign, with an optional note; {"verdict": null} withdraws it. The lookup above returns it as analyst_verdict, analyst_note, decided_by and decided_at.
The same words as a verdict, unlike a file's analyst verdict: a file has a verdict of its own that a person speaks about; an indicator has none — a feed is a third party and the reputation score a heuristic — so the person's conclusion is the verdict.
| verdict | effect |
|---|---|
malicious, suspicious | An assertion: an indicator in a case's STIX export, an entry on its block list, and +30 on the reputation score. |
benign | Off a case's block list even where a feed lists it, out of a STIX export's indicators (it still travels as an observable) and refused from a published collection, and −30 on the reputation score. |
A note is required to mark benign a value a public feed or one of your intel subscriptions lists (400 otherwise). 404 if your organisation has never encountered the value. Recorded in the audit log and on the timeline of any case holding it.
curl -X PUT "https://app.threatera.eu/api/iocs/evil-c2.sbs/verdict" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"verdict":"malicious","note":"beacons every 60s from the dropper"}'
Files that reference this indicator (the IOC → file pivot). Each carries
how:
strings | Found in the file itself — its text, a link or QR code it carries (a PDF's link, a page's form destination, an Office document's remote template), or a decoded configuration. Evidence the value is present — it may equally be a C2, a comment, or a library's vendor URL. |
sandbox network | The sample reached it while running. Code that executed went there, which is evidence of intent. |
strings + sandbox network | Both, and strictly stronger than either — written into the file and contacted. |
null | Not recorded. The link predates this field. It is not a claim that the indicator was found some other way, and it is deliberately not defaulted — the whole point of the column is to distinguish a guess from an observation. |
Blocking decisions turn on which of these you have, and before this field existed the two were indistinguishable in the same row.
URL sandbox runs that contacted this indicator (the IOC → URL-scan pivot).
How often your organisation has met this indicator, day by day.
?days= sets the window (1–90, default 14).
The running counter on the indicator itself answers
how significant is this and cannot answer is it getting worse.
Four hundred sightings spread over a year is infrastructure somebody should
have blocked long ago; four hundred that all arrived on Tuesday is an
incident. The counter renders both as 400.
{
"value": "c2.example.test",
"days": [ {"day": "2026-08-16", "count": 0}, … {"day": "2026-08-29", "count": 37} ],
"total_in_window": 91,
"total": 412,
"recording_since": "2026-08-20"
}
Three things worth reading carefully:
- The series is dense. Every day in the window is present, zeroes included, so a client can draw it without re-densifying a sparse list — which is where an off-by-one puts Tuesday's spike on Wednesday.
recording_sinceis where the record begins. Per-day counting started with a migration and was deliberately not backfilled: the platform never recorded when a repeat sighting happened, only that the count went up, so any earlier history would be a distribution nobody observed. A zero before this date means "not counting yet", which is the opposite of what a zero after it means. Draw them differently.total_in_windowis nottotal. They differ for any indicator older than the window. Reporting one as the other makes the chart look broken.
404 if the indicator is unknown to the platform.
DNS history. The direction depends on what you ask about, and the reverse case is the interesting one:
| Indicator | direction | Returns |
|---|---|---|
| A domain | domain_to_ip | The addresses it has been seen resolving to. |
| An IP | ip_to_domain | Every domain observed resolving to it — how you find shared infrastructure. |
{
"value": "93.184.216.34", "type": "ip", "direction": "ip_to_domain",
"active_dns": { "status": "not_applicable" },
"results": [{
"domain": "example.com", "ip": "93.184.216.34", "count": 4,
"source": "urlscan",
"first_seen": "2026-07-14T10:02:11Z", "last_seen": "2026-07-26T18:44:03Z"
}]
}urlscan is passive — the address a scan's traffic actually reached, learned at no extra cost — while active is a live lookup this endpoint performed.Live lookups
For a domain, the endpoint may resolve the name itself, and reports what it did in active_dns.status: disabled, cached (something was already observed within ACTIVE_DNS_CACHE_MINUTES), resolved, error, or not_applicable for an IP. A failed lookup is never recorded — "we could not ask" is not an observation.
| Name | Type | Description |
|---|---|---|
| refresh | bool | Resolve again even if a recent observation exists. Default false. |
ACTIVE_DNS_ENABLED when timeliness is worth being seen.400 if the value is not a valid IP or domain.
A risk score for an indicator, computed entirely from your own instance's data — the files that reference it and their verdicts, sandbox runs that contacted it, analyst tags, and registration age.
Response
{
"value": "evil-c2.com", "type": "domain",
"score": 75, "band": "malicious", "confidence": "high",
"signals": [
{"label":"extracted from malicious files","weight":45,"detail":"2 file(s) …"},
{"label":"labelled by an analyst","weight":30,"detail":"tagged c2"}
],
"evidence": {"linked_files":2,"malicious_files":2,"sandbox_runs":0, …},
"pending": [],
"gaps": ["Registration age is not known — .at publishes no RDAP service …"],
"basis": "Computed only from this instance's own data …"
}Bands
| Band | Meaning |
|---|---|
malicious | score ≥ 70 |
suspicious | score ≥ 40 |
unknown | score ≥ 15, or no evidence at all |
likely-benign | the platform has looked and found nothing bad |
An indicator with no evidence returns unknown, never benign. That distinction is the point: a confident "clean" on something the platform has never encountered would be inventing reassurance out of an empty database. likely-benign means it was examined; unknown means it wasn't.
The score is exactly the sum of the signals weights (clamped to 0–100), and every signal carries the evidence behind it — an analyst has to be able to disagree with the number, which means seeing what produced it. confidence reflects how much evidence exists, separately from what it concluded.
Two lists say what the score could not use. pending is what will fill in — today only a domain's registration age before its registration lookup has run, so ask again once it has. gaps is what will not: registration lookups switched off, a registry that answered without a date, or a TLD whose registry publishes no RDAP service at all (.de, .at, .ch, .eu and .it among them). A gap is stated rather than left out, because a score silently missing a signal reads as one that found nothing.
Registration data via RDAP — the structured successor to WHOIS. For a domain: registrar, registration/expiry/last-changed dates, nameservers and EPP status codes. For an IP: the allocated network range, organisation, country and abuse contact.
RDAP_ENABLED once that trade is acceptable for your deployment.While disabled the endpoint still returns 200, with "enabled": false and an explanatory error — a turned-off feature is a state, not a failure. No network call is made.
Response
{
"value": "example.com", "type": "domain",
"enabled": true, "cached": true, "error": null,
"registrar": "Example Registrar, Inc.",
"registered_at": "1995-08-14T04:00:00+00:00",
"expires_at": "2027-08-13T04:00:00+00:00",
"nameservers": ["a.iana-servers.net", "b.iana-servers.net"],
"statuses": ["client transfer prohibited"],
"raw": "{…the registry's full RDAP response…}"
}raw carries the complete registry response as a JSON string. The parsed fields above cover the common case, but registries put useful detail in fields nobody standardised — reseller, DNSSEC state, registrant hints — so this is where an analyst looks when the summary is not enough. Typically a few KB; hard-capped by RDAP_MAX_RESPONSE_BYTES. The UI shows it collapsed under the summary table.
Queries go to the authoritative registry, discovered through the IANA bootstrap — never through a public redirector such as rdap.org, so no aggregator learns what you look up.
Results are cached for RDAP_CACHE_DAYS (default 7). Failures are cached too: a TLD that publishes no RDAP service, or a domain that isn't registered, would otherwise be re-asked on every page view. cached: true tells you the answer came from that cache.
Coverage — read this before concluding it is broken
RDAP is mandatory for gTLDs (.com, .net, .org, .io, .dev, …) and those return full detail. It is voluntary for country-code TLDs, and many European registries either publish nothing or redact almost everything:
| TLD | Result |
|---|---|
.com .net .org .io and ~1200 more | Full detail — registrar, dates, nameservers, status |
.de, .ch | Reachable, but heavily redacted under GDPR — often nameservers only, no registrar or dates |
.eu, .at, .it, .es, .se | No reachable RDAP service — returns an explanatory error |
An empty or sparse panel for a European domain is therefore usually the registry's disclosure policy, not a failure here. Threatera does not fall back to port-43 WHOIS.
A slow, rate-limiting or malformed registry never fails the request — the reason arrives in error and the rest of the indicator page is unaffected.
URL sandbox
Render a URL in an isolated headless browser and capture the screenshot, final URL, page content, every network request, contacted indicators, and the TLS certificate. Guarded against SSRF on every request.
Queue a sandboxed render. Returns 202 with a pending scan; poll the scan endpoint. A URL that resolves to internal/private space is rejected with 400.
Body (application/json)
| Field | Type | Description |
|---|---|---|
| url required | string | The URL to render. |
curl -X POST https://app.threatera.eu/api/urlscans \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"url":"https://example.com"}'
A URL sandbox run by id.
{
"id": 31, "url": "https://example.com", "status": "completed",
"result": {
"final_url": "https://example.com/", "title": "Example Domain",
"screenshot_object": "urlscans/31.png",
"requests": [{"url":"…","method":"GET","status":200,"remote_ip":"…"}],
"certificate": {"subject_cn":"example.com","issuer_cn":"…","not_after":"…",
"tls_version":"TLSv1.3","sha256":"…","sans":["example.com"]},
"iocs": [{"type":"domain","value":"example.com"}]
}
}List URL scans, most recently submitted first. Params: url (prefix match), since (submitted at or after, ISO), limit, offset, include_dismissed. Each row carries id, url, status, error, created_at and completed_at — not the result, which holds the page's whole HTML and every request it made (up to a few hundred KB a scan). Open one with GET /urlscans/{id} for that.
include_dismissed is true here, unlike GET /detonations: this endpoint also answers “has this URL been scanned”, and a scan somebody cleared out of the sandbox queue is still a scan of that URL. The sandbox list passes false.
The rendered page's screenshot (PNG). 404 if unavailable.
curl https://app.threatera.eu/api/urlscans/31/screenshot \ -H "x-api-key: $THREATERA_KEY" -o shot.png
Your other scanned pages that look like this one, whatever domain served them — how one phishing kit deployed on many domains shows. Each screenshot carries a 64-bit perceptual fingerprint of its layout (greyscale, so a recoloured copy still matches); twins are your scans at most match_bits (10) bits away, other domains first, each with its similarity (the share of the fingerprints' bits that agree — a measure of the fingerprints, not of the pages), its registrable site and same_site. other_sites counts the other domains. impersonates lists your own pages (marked as yours) it looks like while served from another registrable domain. status other than ok says why nothing was compared: no_screenshot, plain (a blank or one-colour render, which every other blank page would match) or not_yet. Older scans are fingerprinted when first asked, up to 40 a request; not_yet_compared counts the rest. Only your organisation's scans are compared. 404 for a scan that is not yours.
Say this scan is of your own page — your sign-in, say — with body {"name": "Our sign-in"}. From then on a scanned page that looks like it on another registrable domain is listed as a likely impersonation. Only a finished scan with a screenshot (400 otherwise). Recorded in the audit log. 404 for a scan that is not yours.
Stop treating this scan as your own page. Recorded in the audit log. 404 for a scan that is not yours.
Every scanned page that looks like one of your own pages but is served from another registrable domain, newest first. our_pages are the scans marked as yours; each of impersonations carries copies — which of them it looks like, with the similarity. A page on your own domain or a subdomain of it is never listed. Only your organisation's scans are compared.
Download the captured TLS certificate as PEM. 404 if none was captured (not https, or the handshake failed).
curl https://app.threatera.eu/api/urlscans/31/certificate \ -H "x-api-key: $THREATERA_KEY" -o cert.pem
Indicators (hosts/IPs) contacted during the scan, each with first_seen — when your organisation first met it, never when anyone else did.
URL indicators
Whole URLs — path and query — that your organisation has met: fetched or run by a script (including layers it decodes), linked in a reported message, linked from a document (a PDF, an HTML or SVG page, an Office file's template or link), opened by a QR code, or loaded by a URL scan. A binary's URLs are not among them: there a documentation link reads the same as a gate. The host alone is useless on a shared host such as raw.githubusercontent.com; the path is what a proxy blocks.
?u=…), a reset link a token. URL indicators are stored per organisation, never published over TAXII, and expire with the evidence they came from — kept while a file, message or scan here still shows them, or while a case holds them or an analyst has decided on them.Most recently seen first. Params: q (substring), host, verdict (malicious, suspicious, benign or undecided), source_kind + source_ref (the URLs one file, message or scan showed — file + SHA-256, email + message id, urlscan + scan id), limit, offset. Each carries id, url, host, counter (distinct artefacts it was met in), sources, the analyst verdict and the times.
One URL, with seen_in (each artefact, how it showed the URL, a link) and assertion — the sentence a case's block list and STIX export would carry, or null when nothing here asserts it. Linked from cases and alerts as /urls/{id}.
Body: { "verdict": "malicious"|"suspicious"|"benign"|null, "note"? }. malicious or suspicious lets a case's block list (type url, Defender Url) and STIX export carry it; benign withholds it from both whatever a feed says; null withdraws the decision.
Your record of one URL, by value: ?url=https://…, normalised first (scheme and host lowercased, default port and fragment dropped). 404 when your organisation has none — the same answer as for a URL another organisation holds.
A case takes a URL as { "kind": "url", "ref": "<id>" }, and a watch rule of kind url matches it exactly or, written with a trailing *, by prefix. Search returns them under urls.
Detonations
File detonations are queued via POST /files/{hash}/detonate; these endpoints browse the results. See Get detonation for the result shape.
Recent detonation runs, newest first — each with the file's hash and first-seen filename. Params: since (requested at or after, ISO), limit, offset, include_dismissed. Returns { "total": n, "results": [...] }.
include_dismissed is false by default: runs an analyst has cleared out of the sandbox queue are left out, and total counts the same set the page is drawn from. Pass true to see them. Note that GET /urlscans defaults the other way — it also answers “has this URL been scanned”, and a scan somebody set aside is still a scan of that URL.
Clear several sandbox runs out of the queue, or put them back. The sandbox list is the union of two endpoints, so each run is named by both halves of its identity:
{ "runs": [ { "kind": "file", "id": 41 }, { "kind": "url", "id": 9 } ], "dismissed": true }kind is file (a detonation) or url (a URL scan); anything else is a 400 rather than a silent no-op, because this is the one place a client composes the pair by hand. dismissed defaults to true; send false to put runs back. Capped at 500 ids per kind.
include_dismissed=true. That distinction is the point — a long failed band is worth reading precisely because it is long, since forty failures sharing one error is a broken backend, and deleting them would clear the queue by destroying the only evidence of it.Reports what it did rather than that it succeeded: dismissed counts the rows actually changed and missing names the ones that were not yours to touch, so a caller that selected forty and changed thirty-seven can tell.
{ "dismissed": 2, "missing": [] }Submit several sandbox runs again. Same runs shape as above; returns 202.
Each detonation is repeated with its own network_mode, args and trace rather than with today's defaults — a run reproduced under different containment has not been reproduced. A re-run is a new run, never an edit of the old one, so “this failed on Tuesday and passed on Friday” stays readable.
{ "queued": ["file:112", "url:78"], "failed": [ { "run": "file:41", "reason": "the file is no longer stored" } ] }failed names anything that could not be queued — an unknown run, a file this organisation no longer holds, a sample that is no longer eligible, or a URL that no longer resolves to a public address (the check is repeated on every scan, and a phishing domain taken down since the first one fails it).
A single detonation run by id (DetonationResponse).
The result carries a persistence list — the filesystem changes that would outlive the process, each with the mechanism and what it means. This is the answer to "is the host still compromised", as opposed to dropped_files, which is everything the sample wrote.
mechanism | where |
|---|---|
cron | /etc/cron.d, /etc/cron.*, /etc/crontab, /var/spool/cron |
systemd | /etc/systemd/system, /usr/lib/systemd/system |
init | /etc/init.d, /etc/rc.local |
preload | /etc/ld.so.preload — a library in every process on the host |
shell | /etc/profile.d, /etc/profile, ~/.bashrc, ~/.zshrc |
ssh | authorized_keys |
udev | /etc/udev/rules.d |
package-manager | /etc/apt/apt.conf.d hooks |
ld.so.preload or truncating a shell profile is tampering. The scan runs over the whole filesystem diff rather than the capped dropped_files list, so a sample that writes three hundred files cannot hide its one cron entry behind a display limit.Each finding is also emitted as a Sigma event under the persistence category, so a rule can select on Mechanism instead of on a path list that drifts out of step with the sandbox.
Cases
Every other endpoint here analyses one artefact. A case is where you say which artefacts were the same incident — files, indicators, sandbox runs and reported email, with a status, a severity, an assignee and a note against each item explaining why it belongs.
Cases in your organisation, newest first. Params: status (open|monitoring|closed, or active for open and monitoring, or unreviewed for closed with no post-incident review — the two the dashboard counts), assignee, q (matches reference, title or summary), sort, limit, offset. Each result carries item_count.
sort is field:asc or field:desc over created_at, updated_at, reference, title, status, assignee, item_count or severity. Severity orders by rank, not alphabetically — sorted as text, critical comes before low and high before medium, which produces a list that looks ordered and is wrong at the moment somebody is scanning it for the worst thing.
| Method & path | Description |
|---|---|
POST /api/cases | Open one. Body: { "title", "summary", "severity", "assignee" }. The reference (CASE-2026-014) is allocated per organisation, per year — sequential within your tenant, so it never discloses how many cases anyone else has opened. |
PATCH /api/cases/{id} | Retitle, reassign, reprioritise or change status. Body: { "title", "summary", "status", "severity", "assignee" }, all optional. Send "assignee": null to unassign — omitting the field leaves it alone. Setting status to closed stamps closed_at; reopening clears it. |
DELETE /api/cases/{id} | Delete the case and its links. The artefacts are untouched. |
One case with its contents. Each item is resolved back to the live artefact at read time and returned with a label, a detail line and an href into the UI.
It also carries impact, review, review_updated_at and review_updated_by (impact, review), and affected_count — how many hosts, accounts and systems are recorded.
found: false, its ref intact and no href. Links are stored as (kind, ref) with no foreign key — which is what lets a new artefact type be added without a schema migration, and costs the guarantee that every link still points somewhere. Hiding a dangling item would silently shrink the case; rendering it as a link would send an analyst to a 404. Reporting it is both honest and useful: it is evidence something was removed.Apply the same change to several cases — closing a week's work, or handing a queue to somebody. Body: { "ids": [...], "status", "severity", "assignee" }, each field optional and applied only when sent.
{ "ids": [41, 42, 43], "status": "closed" }"assignee": null unassigns, which is a different instruction from leaving the field out. The two cannot be told apart by value, so they are told apart by presence — the same distinction PATCH /cases/{id} makes. A client that omits the key to mean "nobody" will find nothing changed.Already in that state is not counted as a change. Closing four of twelve selected, because eight were closed already, reports four. closed_at is stamped on close and cleared on reopen rather than derived later: "how long was this open" is a number customers ask for, and reconstructing it from the audit log is fragile once events are ever pruned.
One audit entry for the batch, one event per case. The two want opposite things from the same action — a log read by a person is buried by twelve rows written in the same second, while an event sink is a machine tracking state, and a single summarising message would leave eleven cases stale downstream with nothing to reconcile against. Only status changes emit case.status_changed: a SOC routes on "this closed" and would mute a channel that also fired on a reassignment.
missing names ids that were not yours to touch. Capped at 500.
{ "changed": 4, "unchanged": 8, "closed": 4, "missing": [] }Attach an artefact. Body: { "kind", "ref", "note" }.
kind | ref is |
|---|---|
file | the SHA-256 |
ioc | the indicator value |
urlscan | the scan id |
email | the message id |
url | the URL indicator's id (URL indicators) |
409 if it is already attached — a repeat is a mis-click, and a silent no-op would look like the button did nothing. note is optional and is the most useful field here: why this artefact is part of this incident.
404 unless your organisation holds it. The evidence table in the audit pack and in every regulatory draft marks an artefact that is not here as "no longer held", which is only true of one that once was — so only what is here can be attached. Another organisation's artefact and one nobody has get the same answer. A file hash and an ioc value are matched case-insensitively.
Attach several artefacts at once. Body: { "items": [ { "kind", "ref", "note" } ], "note" }, with the same kind vocabulary as above. The outer note applies to every link; a per-item note overrides it for that item.
{ "items": [ { "kind": "email", "ref": "41" }, { "kind": "email", "ref": "42" } ],
"note": "same lure, same sender domain, reported within the hour" }already instead.The same artefact named twice in one request is attached once. Capped at 500 items, and one audit entry is written for the batch rather than one per link.
What your organisation does not hold is not attached and is named in missing, the way already names what was there — the rest of the batch still attaches.
{ "added": 36, "already": 3, "missing": [ { "kind": "file", "ref": "…" } ], "items": [ ... ] }| Method & path | Description |
|---|---|
DELETE /api/cases/{id}/items/{item_id} | Detach it. The artefact itself is untouched. |
The case told in order, oldest first: { "entries": [...], "earliest_evidence": {...} | null, "hindsight": {...} }. Assembled on every call from what is already recorded about the case and every artefact in it — when each file arrived, when its analysis and sandbox runs finished and what they said, hunt matches, EDR detections, when an indicator was first seen or matched the watchlist, when a URL was scanned, when a phishing report came in and was decided, when the case was opened and each artefact added, the regulatory anchors and every filing. Nothing in it is stored twice.
{ "at": "2026-10-01T09:12:00+00:00",
"what": "Defender detected invoice.exe (Trojan:Win32/Agent)",
"provenance": "reported", "by": "Defender",
"kind": "file", "ref": "9f86d0…", "href": "/files/9f86d0…",
"detail": null, "id": null }Every entry says who says so. recorded is this platform's own clock at the moment it happened. reported is another system's account that was written down here — an EDR vendor's detection time, or a reported message's own Date header, which whoever sent it chose. stated is a person: the regulatory anchors they entered, and notes added below. Nothing is inferred — a message with no Date header gets no "sent" line.
earliest_evidence is the first entry that is neither stated nor the investigation's own bookkeeping (opening the case, adding to it, filing) — the earliest moment anything recorded or reported touched this incident, which is what the regulatory began_at is usually asked to reflect. The device an EDR names appears only for an organisation's admins.
hindsight asks Hindsight about every file, indicator and link in the case: was it here before anybody knew it was harmful? found lists each that was, with first_contact_at (and what that contact was), known_at, who made it known (known_by: feed, subscription — one of your own intel subscriptions, by its publisher’s date — analysis or analyst, and known_name), dwell_seconds and head_start in words; earliest_contact_at and longest_seconds sum it up. A feed or one of your subscriptions publishing a value already here becomes a reported entry of kind intel, which never counts as the earliest evidence: it is when the world learnt, not when the incident happened. At most 40 artefacts are asked; asked, of and limited say when a large case was cut short. The case report carries the same as "Here before it was known".
Put something a person knows on the timeline: { "occurred_at": "2026-10-01T02:14:00+02:00", "text": "VPN login as j.doe from 185.x", "source": "firewall logs" }. 201. It appears as stated, by whoever added it. occurred_at needs a timezone offset — a bare time would be placed in somebody's zone hours from the evidence beside it — and may not be in the future. source is optional and is what makes the statement checkable.
Remove a stated entry (id on the entry). 204. Only those: everything else on the timeline is the record of what happened, and detaching an artefact from the case is how its lines go. The audit log keeps what was said.
The hosts, accounts and systems this incident reached, ordered by kind and name. Each entry: { "id", "kind", "name", "criticality", "business_unit", "notes", "affected_at", "contained_at", "edr_detection_id", "added_by", "added_at" }. kind is host, account or system; criticality is low, medium, high, critical or null (not assessed).
The two times are a person's statement, and the timeline says so. affected_at and contained_at appear on the timeline as stated entries — "Host affected", "Host contained" — beside the recorded moment the entry was added here. A host taken from an EDR detection also brings that detection's own time, as reported.
Record one: { "kind": "host", "name": "WS-0142", "criticality": "high", "business_unit": "Finance", "affected_at": "2026-10-01T02:14:00+02:00" }. 201 when new; 200 with the entry already there when the same kind and name are recorded on this case — "WS-0142" and " ws-0142" are one host. contained_at before affected_at is a 422.
From an EDR detection: { "edr_detection_id": 812 } records that detection's device as a host, with nothing else to type. Administrators only — 403, asked before the detection is looked up, because EDR detections and the machine names in them are an administrator's view, and putting one on a case is the decision to show that name to everyone working it. 404 for a detection that is not your organisation's; 400 for one that names no device.
Change criticality, business_unit, notes, affected_at or contained_at. Only the fields sent change; an explicit null clears one. The kind and the name are what the entry is, so they do not change — remove it and record the right one. 400 if the result would be contained before it was affected.
Take an entry off the case — recorded by mistake, or out of scope. 204. The audit log keeps that it was there.
What the incident cost the organisation. Replaces the whole impact; returns { "impact": {...} | null }, which GET /api/cases/{id} also carries.
{ "business_units": ["Finance", "Payroll"],
"affected_users": "unknown",
"data_categories": ["customer contact data"],
"service_disruption": "yes", "disruption_hours": 6 }A field left out was not assessed; "unknown" says somebody looked and could not tell. They are different answers to a regulator, so both exist: business_units, affected_users and data_categories take a value or "unknown", and service_disruption is yes, no or unknown. disruption_hours only with yes. Unknown fields are a 422, so a misspelt key is not silently stored as nothing. There is no cost field.
The post-incident review: { "what_happened", "root_cause", "what_worked", "what_to_change", "follow_ups": [{ "action", "owner", "due" }] }, every part optional. Replaces the whole review and stamps who wrote it and when; returns { "review", "review_updated_at", "review_updated_by" }, which the case also carries. Allowed on an open case as well as a closed one — reviews are often started before the last host is clean. due is a date (2026-11-01).
A closed case with no review is not blocked, but it is counted: closed_without_review in the dashboard totals (all time) and in the case metrics (closed in the window).
The case as a STIX 2.1 bundle — application/stix+json;version=2.1, downloaded as CASE-2026-001.stix.json. For a customer's TIP, a partner's MISP, or a CERT intake.
file, domain-name, ipv4-addr, url, email-message. An indicator carries a detection pattern a receiving SIEM will alert on, so one is emitted only where this platform holds an actual assertion. Mapping every artefact to an indicator is the easy shape and the wrong one: a phishing case legitimately contains login.microsoftonline.com, and telling a partner to alert on it is worse than sending nothing.| An indicator is emitted when… | and says |
|---|---|
A file's analysis returned malicious or suspicious | the verdict, and any YARA rules that matched |
| A public threat feed lists the value | which feeds |
An analyst marked (or, through the submit route, tagged) the indicator malicious or suspicious | that it was marked by this organisation |
The analyst's mark is the promotion path that matters operationally: a C2 domain registered this morning is in no public corpus on the day you need to tell somebody about it.
Identifiers are deterministic. Observables take a UUIDv5 over their ID-contributing properties (STIX 2.1 § 2.9), so the same file exported from two cases is one object on arrival. The report and indicators are keyed on the case reference, so re-exporting updates the receiver's copy instead of adding a report per run.
Per-item notes are not exported. The free-text "why this belongs" is internal commentary and routinely names staff, customers and working hypotheses. The report's description carries the case summary, which is written to be read.
TLP markings
An artefact an analyst here marked false_positive or benign travels as an observable without its indicator — sending one would tell a partner's SIEM to alert on something this organisation concluded is not a threat — and the response header X-Threatera-Withheld counts them, for the person exporting. The bundle itself carries no note.
If any artefact in the case arrived through one of your intel subscriptions carrying a TLP marking, the bundle gains a marking-definition object and every other object in it gets an object_marking_refs pointing at that marking. The level applied is the most restrictive any contributing indicator arrived under — mixing an AMBER indicator into a GREEN bundle downgrades the AMBER one, which is the failure worth avoiding.
{"type":"marking-definition","spec_version":"2.1",
"id":"marking-definition--55d920b0-5e8b-4f79-9ee9-91f868d9b421",
"name":"TLP:AMBER","created":"2022-10-01T00:00:00.000Z"}definition block — the id and name are the whole of it, and adding a 1.0-style one would make the object invalid under both versions.This is what stops the export button breaching a sharing agreement. An indicator a CERT sent you as TLP:AMBER may not be passed outside your organisation; it lands in a case like anything else, and the case has a one-click export aimed at exactly the third parties the marking excludes. A case with nothing marked in it exports unmarked, as before.
What the case says to block, for a firewall's external list or an EDR's custom indicators. The STIX export is the report; this is the defence.
What a download leaves out is said beside it. A firewall's list has no room for a comment, so every download carries X-Blocklist-Withheld (how many attached artefacts are not in it) and X-Blocklist-Expired (how many of those because they went unseen longer than your expiry period); format=json gives each one with its reason, as withheld and left_out.
malicious or suspicious verdict, a public feed listing, or an analyst's malicious/suspicious tag on the indicator — decided by the same code. A phishing case holds the real sign-in page it imitated, and a list built from attachments would block it at the next import.Two things can only take an entry off: a private or reserved address or internal name is never listed (what a sample reached inside a sandbox says nothing about the same address on your network), and a file an analyst here marked false_positive or benign, or an indicator marked benign, is withheld — from the STIX export and a published collection too, by the same functions. Nothing a person concludes can put one on — only evidence does.
format | returns |
|---|---|
json (default) | entries (type, value, reason, source), withheld — every attached artefact left off, with the reason and how to change it — counts by type, and tlp |
txt | One value per line and nothing else, for a firewall's external dynamic list. type is required — such a list holds one kind of value: sha256, sha1, md5, domain or ip. |
csv | type,value,reason,from,marking, optionally narrowed by type |
defender | Microsoft Defender for Endpoint's indicator import (Settings › Endpoints › Indicators › Import). Files are BlockAndRemediate, addresses and domains Block, severity from the case. MD5 is not a type Defender imports and is left out; Defender takes 500 rows per file. |
curl "https://app.threatera.eu/api/cases/14/blocklist?format=txt&type=domain" \ -H "x-api-key: $THREATERA_KEY"
Each entry carries the most restrictive TLP marking any listed value arrived under, as tlp and in the CSV's marking column. A download is recorded in the audit log, as a STIX export is; the JSON preview is not.
The case as one document, for somebody without an account — management, an insurer, a regulator's file. format=md (default) or pdf. It holds the facts and summary, the artefacts, the timeline with who says so for every line, the checklists, the block list, the affected hosts, accounts and systems, the business impact, the post-incident review, the reporting stages and the related cases, from the same services the case's screen reads.
Written in your organisation's report language; lang=en or lang=de asks for another. A German report whose translation is not yet approved by a reviewer says so at the top. Timeline lines and checklist steps stay English, and what people wrote stays as they wrote it.
The steps an incident of a given kind needs, on the case. Returns checklists — each with its steps and progress (settled of total) — and templates, every kind the case could have: phishing, malware, ransomware.
step kind | ticked by |
|---|---|
observed | The platform, from the case itself, on every read — the message is attached, every file analysed, the sample run in the sandbox, a YARA rule matches it, the C2 marked, the awareness time recorded. evidence says what it saw. A person cannot mark one done. |
manual | A person — isolating an endpoint, resetting a password. by and at say who and when. |
A step's state is open, done or not_needed. An observation with nothing to look at yet ("every attached file is analysed" in a case with no files) stays open rather than passing vacuously.
Put a checklist on the case: {"template": "phishing"}. 201 with the checklist; 409 if the case already has that kind; 400 for an unknown template.
Mark one step: {"state": "done" | "not_needed" | "open", "note": "…"}. open takes a person's mark back off. An observed step cannot be marked done (400) — it can be marked not_needed. A note is required for not_needed: a step skipped without a reason is indistinguishable from one forgotten. Each mark is in the audit log.
curl -X PUT "https://app.threatera.eu/api/cases/14/checklists/3/steps/isolated" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"state":"done","note":"EDR network containment, 09:42"}'
Take a checklist off the case, with what people marked on it. 204. The audit log keeps each mark.
The case's tasks — who does what by when — open ones first, soonest due first. Each has title, assignee, due_at, status (open, done, cancelled), who made it and when, who finished it and when, and, if it was made from a checklist step, checklist_id and checklist_step.
Give the case a task: title, and optionally assignee — a member of this organisation, 400 otherwise, with the same answer whether the name belongs to an account elsewhere or to none — and due_at. With checklist_id and checklist_step it is made from that step of one of this case's checklists and takes its text as the title unless one is given. The owner is notified, unless they made it themselves. 201.
curl -X POST https://app.threatera.eu/api/cases/<id>/tasks \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"checklist_id":12,"checklist_step":"purged","assignee":"anna@example.com","due_at":"2026-10-20T16:00:00Z"}'
Retitle, reassign, re-date, or set status. Only the fields sent change; null clears an owner or a due time. done records who and when, and the case timeline shows the completion as a recorded line; reopening clears both. A new owner is notified.
Delete a task made by mistake. To record that it will not happen, set its status to cancelled instead, which keeps it on the case and in the case report. 204.
How long cases take, over the last days (1–365, default 90): opened, closed, open_now, the oldest_open case, and two durations named for what they measure.
| field | measures |
|---|---|
opened_to_closed | The investigation. A case reopened and closed again runs from its first opening to its last close. |
aware_to_closed | The incident, from when the organisation knew — the NIS2/DORA clock. Over only the cases where awareness was recorded, and cases says how many: a median over three is not a median over forty. |
Each has cases, median_hours and a nearest-rank p90_hours — a value a case actually took, never an interpolation — null when no case qualifies. by_severity gives the first per severity.
| field | holds |
|---|---|
affected_by_severity | For the cases opened in the window, per severity, how many hosts, accounts and systems they recorded as affected. |
time_to_contain | entities, median_hours and p90_hours from affected to contained, over only the entries where a person recorded both times. without_both_times counts the rest. A containment time nobody wrote down is not zero and not the case's closing time, so it is counted and said, never filled in. |
closed_without_review | Cases closed in the window with no post-incident review. |
Which cases already reference this artefact — the reverse lookup, and the reason it has its own index. It is what lets a file or indicator page say already part of CASE-2026-014 instead of an analyst opening a second investigation into something already being worked.
Knowledge base
Your organisation's own pages about the malware families and actors it keeps meeting — "this is family X, it behaves like this" — linked to the files, indicators, campaigns, rules and cases that show it.
Written by your organisation and nothing else: no page is fetched from anywhere. The body is Markdown, rendered with raw HTML shown as text and links opened only when they are http or https. Every edit is kept. A page linked to a campaign appears on each of that campaign's files.
Your organisation's pages, by name: kind, name, aliases, who last edited each and when, and link_count. q searches names, aliases and the text; kind narrows to family, actor or other.
Write a page: kind, name — unique in your organisation, whatever its case, 409 otherwise — aliases and a Markdown body. Kept as the page's first version. 201.
The pages to show on one thing — what its pane lists as Known as: those linked to it, and for a file or an indicator those linked to a campaign it belongs to, each saying via which. A member an analyst threw out of the campaign does not carry the page. An empty list for anything with none, including anything your organisation does not hold.
One page, its links and how many revisions it has.
Edit a page; only the fields sent change. Every edit is kept as a new version with who and when. 409 for a name another page has. Audited.
Delete a page with its links and versions. Audited with its name. 204.
Every version of the page, newest first — name, aliases and body as they were, who wrote them and when. The last is the page as created.
Link the page to a file (SHA-256), an ioc (value), a cluster or a case (id), or a yara or sigma rule (name). 404 unless your organisation holds it — the same answer for another organisation's and for nothing. 200 with the existing link when it is linked already, 201 otherwise.
Take a link off the page. 204.
Saved searches
A search you run often, kept under a name — from Search, Files or Indicators — for yourself, or shared with your organisation.
A saved search is the view's own address (path, such as /files?verdict=malicious, which already carries the verdict, decision and window filters) and the filter boxes the address does not carry (fields: the text query, a tag, a type). Personal ones are seen by you alone; shared ones by every member of your organisation and nobody outside it.
Your saved searches and those shared with your organisation, newest first; tab (search, files, iocs) narrows to one tab. Each has id, tab, name, path, fields, shared, mine and owner.
Keep a search: tab, name, path — which must be an address inside that tab — fields (at most ten, names a view uses, values up to 500 characters) and shared. Any member may save their own, read-only included; sharing needs the right to change things (403 otherwise) and is audited. 201.
curl -X POST https://app.threatera.eu/api/saved-searches \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"tab":"files","name":"Undecided malicious","path":"/files?verdict=malicious&decided=no","shared":true}'
Delete one of yours, or — as an admin — a shared one. 404 for one you cannot see (a colleague's personal search, another organisation's, none at all); 403 for a colleague's shared one. 204.
Notifications
What needs you, in the organisation you are acting in — shown as the bell in the header.
A notification is written when somebody assigns you a case or a task, when somebody mentions you as @name in a comment, and — by an hourly check — when a task of yours is due within 24 hours or overdue, or a reporting stage on a case assigned to you is. Each is said once: the hourly check keys what it writes by the deadline, so a re-run tells nobody twice, and moving a due date is a new deadline. Nobody is told about their own act, and only members who may act in the organisation now are told anything; mentioning a name that is not one changes nothing, and the comment is answered exactly as one without a mention. Nothing is mailed.
Your notifications here, newest first (limit, default 50; unread=true for unread only), and unread, how many are unread. Each has kind (case_assigned, mention, task_assigned, task_due, task_overdue, stage_due, collector_silent — to owners and admins, once per silence, linking to /tenants/collectors; federation_warning — to owners, admins and analysts, once per value, linking to its page; hindsight — to owners, admins and analysts, once per value), a sentence, a link to what it is about, and read. Only ever your own; the shared service key, which is not a person, has none.
Mark notifications read: {"ids": […]}, or every unread one when ids is omitted. Answers {"marked": n}, how many changed; an id that is not yours changes nothing and counts as nothing, the same as one that does not exist. Open to every member, read-only included — it is about what you were told.
Executive view
Posture over months, performance against the targets your organisation sets, and a monthly document for management — built from the same records the case screens read.
null; the month it began in is marked partial. The monthly report prints the same gaps in words.What the platform did for your organisation over the last days (30, 90 or 365; default 90) — the “What Threatera did for you” report — from its own records only. files: files judged in the window (each file's latest verdict), how many malicious and suspicious, and the median seconds from submission to verdict. sandbox: detonations and pages completed. phishing: mail reported, judged malicious or suspicious, decided by a person and the median hours to that decision. campaigns: total, new in the window and the samples grouped. indicators.first_met. impersonations: scanned pages copying a page you marked as yours.
endpoint is the head start: for each file your endpoint protection first flagged in the window, whether the platform's first malicious or suspicious verdict on it for your organisation came earlier (ahead) or later (behind), with median_ahead_hours, median_behind_hours and every file's lead in points_hours (positive: the platform was first). Both directions are reported. Files it flagged that were never submitted here are not_comparable; nothing is said about files it never flagged. status: "no_edr" when none is connected.
Nothing is estimated — there is no “hours saved”. Each section's since is where its record begins when that is later than the window's start. 400 for another days.
The last months (1–24, default 12), oldest first, ending with the current month. recording_since gives, per metric (cases, files, phishing, regulatory, affected), the date its record begins; each month's recorded says full, partial or none for each, and a metric that is none that month is null.
| field | per month |
|---|---|
opened, closed | Cases by severity, by the month they were opened or last closed. |
time_to_close | cases, median_hours and a nearest-rank p90_hours, over cases closed that month. |
first_response | The same for the time from opening to the first assignment or status change, over cases opened that month; awaiting counts those nobody has acted on yet and not_recorded those opened before first response was kept. |
regulatory | Reporting stages by the month they fell due: on_time, late, overdue (not filed, deadline passed) and open (not yet due). A stage with no deadline yet — its clock never started — is in no month. |
files_received | Files submitted directly; an archive's members and the files a sandbox run created are not counted. |
phishing_reports | Reported messages received. |
affected | Hosts, accounts and systems recorded on cases opened that month, by kind. |
Your organisation's response targets — {severity: {first_response_hours, close_hours}}, or null — and how the cases opened this quarter (window) are doing against them. Per severity, performance gives for first_response and close the counts met and missed; a case still open past its target has already missed and is also counted in still_open. A case opened before first response was recorded is not_recorded, never missed.
A case is measured at the severity it has now: a change of severity is not recorded with a time, so the target it had when opened cannot be known.
Set the targets. Admins only — an analyst gets 403. The body replaces them whole; a severity left out, or a field set to null, has no target. Hours, more than 0 and at most a year; 400 says what is wrong. Returns the same answer as GET, and the change is audited.
curl -X PUT https://app.threatera.eu/api/metrics/targets \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"critical":{"first_response_hours":1,"close_hours":24},"high":{"first_response_hours":4,"close_hours":72}}'
Everything the executive view draws, in one answer so no card can disagree with the one beside it. Admins only. trends (twelve months, as above), open cases by severity with each one's age and whether anybody has responded, deadlines falling due in the next seven days (as the regulatory panel), targets with this quarter's performance, and closed_without_review.
One month as a document for management, format=md (default) or pdf; month=YYYY-MM, the previous month when omitted. Admins only. Headline numbers against the month before, cases by severity, reporting deadlines met and missed, response targets, the most severe incidents with a line each, open actions — and what this report cannot tell you, which names every gap in the data behind it: months or metrics not yet recorded, cases with no first response recorded, reportable cases with no awareness time, affected entities without times, and that open actions are as of generation rather than month end. 400 for a month that is malformed or has not begun. The download is audited.
Written in your organisation's report language; lang=en or lang=de asks for another. A German report whose translation is not yet approved by a reviewer says so on its first page.
curl "https://app.threatera.eu/api/reports/monthly?month=2026-09&format=pdf" \ -H "x-api-key: $THREATERA_KEY" -o threatera-2026-09.pdf
The language your organisation's reports are written in — the monthly report, the case report and the NIS2/DORA drafts. The interface stays English. language is en (the default) or de; languages lists each one offered with how many of its strings a reviewer has approved (reviewed).
{"language": "de", "languages": [{"code": "en", "name": "English", "strings": 0, "reviewed": 0}, {"code": "de", "name": "Deutsch", "strings": 218, "reviewed": 0}]}
Set it: {"language": "de"}. Admins only — an analyst gets 403; 400 for a language not offered. Returns the same answer as GET, and the change is audited.
curl -X PUT https://app.threatera.eu/api/reports/language \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"language":"de"}'
Regulatory reporting
A case rendered into what NIS2 (Directive (EU) 2022/2555, Art. 23) and DORA (Regulation (EU) 2022/2554, Art. 19) ask for, with the deadline for each stage.
Every deadline this organisation is carrying, across every open case, worst first. Overdue stages sort above the ones still running. Optional ?within_hours=24 narrows it to a horizon — overdue stages are always included, because a deadline that has passed does not stop being the next thing to do.
Each entry carries the case (case_id, reference, title, severity) alongside the stage (framework, label, citation, due_at, hours_remaining, missing). hours_remaining goes negative once a deadline has passed rather than clamping at zero: "3 hours late" and "due now" call for different actions.
summary.unanchored is the number to look at first, and it is not a deadline. It counts open cases that have a framework selected and no awareness time recorded — so no clock is running on them at all. Both regulations run every deadline from the moment the entity became aware, and a case that never recorded it reports every stage as waiting rather than late. It looks calm because nobody started it, which is the quietest way to miss a statutory deadline.curl "https://app.threatera.eu/api/regulatory/due?within_hours=24" -H "x-api-key: $THREATERA_KEY"
The answers recorded for this case, and every stage they imply.
| Method & path | Description |
|---|---|
PUT /api/cases/{id}/regulatory | Record the answers. Only the fields you send are changed. Body: { "frameworks", "aware_at", "began_at", "classified_at", "suspected_malicious", "cross_border", "impact", "root_cause", "mitigation", "affected_clients" }. The two booleans are tri-state — null means nobody has decided, which is different from "no" and blocks the stages that require an answer. The three times need a timezone offset and cannot be in the future (422), and must run in order — began, then aware, then classified (400): every deadline is counted from them, so a bare time read as UTC or a typo of 2062 would move a statutory clock without a word. |
aware_at, not from when the case was opened. Somebody notices at 09:14, tells three people, and a case exists at 11:40 — the 24-hour early warning was due at 09:14 the next day. Anchoring on the case would report two and a half hours of margin that were never there, silently. So awareness is a field a human fills in, and nothing is due until they do.state | meaning |
|---|---|
due | the clock is running; hours_remaining goes negative once it has passed, rather than clamping to zero — "3 hours late" and "due now" call for different actions |
waiting | an earlier stage has to be filed first, so the deadline cannot be computed yet. Not the same as optional |
on-request | the regulation sets no deadline (the NIS2 intermediate report). Inventing one would be a deadline the law does not impose, shown in red |
submitted | somebody recorded that they filed it |
Later stages chain off the previous submission, not off awareness. A NIS2 final report is one month from the notification; for an incident notified on day three, anchoring it on awareness would make it three days early, every time. DORA's initial notification carries two clocks — 4 hours from classifying it as major, 24 from awareness — and the deadline returned is whichever comes first.
missing names the fields that still block a draft, in the words the form uses. An explicitly answered false counts as answered: "no, this is not suspected to be malicious" is what the authority asked for.
suggested is { "impact", "root_cause" }: text for the two prose fields, written from what the case already records — its affected hosts, accounts and systems and business impact, and the root cause from its review. Offered, never stored: the form fills an empty field with it and leaves one somebody has written alone, and nothing reaches the filing until you PUT it. Hosts and accounts are counted, not named, because a filing leaves the organisation; systems are named. Says "unknown" wherever the impact does — a draft that drops "users affected: unknown" reads as "none".
The stage as a Markdown draft, downloaded as CASE-2026-014-nis2-early_warning.md. Markdown because it pastes into any authority portal's textarea and needs no rendering dependency.
In your organisation's report language — but a German draft is produced only once every sentence it needs has been approved by a reviewer. Until then the draft is English and says at the top why. A management report may be a draft translation that says so; a notification to an authority may not. There is no per-download override, so the draft frozen when you mark a stage filed is the one you were shown.
404 for a framework or stage that does not exist. 409 when a mandatory field is still empty, with the list in detail.missing. A draft is refused rather than rendered with gaps — a submission reading "Impact: —" where the authority expects an assessment is worse than none: it looks complete, it goes in the file, and nobody revisits it.
Record that you filed it. Body: { "authority_reference": "CSIRT-AT-2026-1187" }.
The draft is frozen at this point. The case keeps moving; a final report filed in March must show what was said in March, not today's edited summary, or the record of what the authority was actually told is lost. The deadline is copied too, so a later correction to aware_at cannot retroactively turn a timely filing into a late one.
Two digests are frozen with it: content_sha256 identifies the document, and evidence_digest identifies the artefacts it cited. Both are readable through the evidence endpoint.
Everything about one incident, in a zip an auditor can check without trusting you. Downloads as CASE-2026-014-audit-pack.zip.
README.txt what this proves, and what it does not
manifest.json every file with its SHA-256, the filed digests, the chain head
case.json the case, its regulatory answers, its timeline,
what it affected, its impact and its review
evidence.md the artefacts behind the filings, as they stand now
audit-trail.json the audit events naming this case, and the chain's verdict
filings/nis2-notification.md the frozen text, byte for byte
The filings are the bytes stored at submission, not re-rendered. That is the point of the pack: content_sha256 verifies against the file inside it, so an auditor can run sha256sum and compare. A pack that re-rendered would produce a document failing its own digest, which looks exactly like tampering.
The archive is reproducible — entries sorted, timestamps fixed — so two exports of an unchanged case are byte-identical and "is this the same pack you sent in March?" has an answer.
GET /api/audit is: the pack contains the audit trail, which is a record of what everybody in the organisation did.Does a filed report still rest on the evidence it was filed against? Two independent checks that answer different questions:
content_sha256identifies the document. Somebody holding a printout can hash it and compare, without trusting anything this platform says about it.evidence_digestidentifies the artefacts it cited — each one's kind, reference and content hash.matchesre-derives that today.
A mismatch is usually not tampering. The common cause is a retention policy removing a sample whose period ran out — legitimate, and still something a supervisor asking about the filing would want to know. So missing names the artefacts that have gone rather than only reporting that the set moved.
matches: null means the report predates these digests. "We cannot tell" and "it has changed" are different answers, and reporting the first as the second would be an accusation produced by a migration. 404 if the stage has not been filed — a draft is re-rendered from the case every time it is asked for, so there is nothing to check it against.
curl "https://app.threatera.eu/api/cases/14/regulatory/nis2/notification/evidence" \
-H "x-api-key: $THREATERA_KEY"
Intel subscriptions
The receiving half. A case exports as a STIX 2.1 bundle; this is where intelligence arrives — a TAXII 2.1 collection from a national CERT, a MISP instance run by an ISAC. What comes in surfaces as enrichment on the indicator page, is swept by the watchlist, and carries its TLP marking through to any export.
<timestamp>". It names no indicator, no hash and no file, so the publisher learns that this installation is subscribed and when it last polled — which they already know, because the customer signed up. That is categorically different from a per-lookup query, which would tell a third party which indicator an analyst is investigating right now. It is why RDAP is off by default and this is not.Which outside parties this organisation receives from. Readable by any member — knowing who your platform talks to is an assurance mechanism, and hiding it from analysts only means the person who notices something odd is the one who cannot look. The stored credential is never returned, to anybody; has_secret says whether one is set.
| Method & path | Description |
|---|---|
POST /api/intel/sources | Subscribe. Body: { "name", "kind", "url", "collection", "username", "secret", "default_tlp", "enabled", "alert_on_seen" }. kind is taxii or misp; enabled and alert_on_seen default to true. Admin only. Nothing is fetched here — the first poll is on the schedule, or via Sync now. The URL must be externally routable: it is checked when saved, before every poll, and at the moment each connection opens, which goes to the address that was checked — a name that answers publicly for the check and privately afterwards is refused, and redirects are not followed. |
PATCH /api/intel/sources/{id} | Rename, re-point, re-credential, pause or quieten: { "name", "url", "collection", "username", "secret", "default_tlp", "enabled", "alert_on_seen" }, all optional. Omitting secret leaves the stored one alone; sending "" clears it. Changing the URL or collection resets the cursor, because the old one means nothing to a new corpus. "enabled": false stops polling and keeps everything already imported. kind is immutable — the cursor and every stored indicator belong to one protocol's idea of identity; delete and re-add instead. |
DELETE /api/intel/sources/{id} | Unsubscribe. The indicators go with it — they were shared under an agreement with that publisher, and some carry a marking that limits holding them. |
TLP is carried through and honoured. default_tlp applies to anything the publisher sends unmarked, and defaults to amber because a collection whose onboarding email says "this is AMBER" and whose objects carry no marking is the ordinary case. Exporting a case that contains such an indicator stamps the bundle with a TLP marking-definition rather than dropping it — without that, the export button would be a way to breach a sharing agreement by accident.
Credentials are stored encrypted with the same key as mailbox passwords. TAXII uses HTTP Basic (or a bearer token when no username is set); MISP uses its API key in a bare Authorization header.
Poll immediately — the same code path the hourly scheduler runs, so a manual poll cannot succeed in a way the scheduled one would not. Returns { "status", "imported", "new", "skipped", "withdrawn", "error" }, and already_seen when something it newly delivered had already been seen here (below).
Already seen here is an alert. With alert_on_seen on, what a poll newly delivers is checked against this organisation's record — the same lookup as Are we affected? — and each match becomes a watch rule labelled with the source (created by intel:<source>, severity high) and an alert in the Inbox for every place it was seen: a file, an indicator, reported mail, a sandbox run or a detection your endpoint protection reported. already_seen is { "seen", "watching", "alerts", "not_raised" }. An indicator an analyst here marked benign is skipped; a re-delivery does not alert again; at most 100 values are raised per poll, and not_raised counts the rest rather than dropping them silently.
A withdrawal stands the rule down. When the publisher revokes a value — or you unsubscribe — the watch rule its delivery created is disabled, not deleted, and its label says when the source named it and when it stopped (stood_down on the poll's result). Its alerts stay in the Inbox with the record of why they fired. A re-delivery re-enables it. It is left exactly as it is when it is no longer purely the source's: somebody edited it or switched it off, somebody here marked the value malicious (or the file confirmed), or another enabled source still lists it.
It reports failure in the body rather than raising. "It failed, and here is why" is more useful to whoever configured it than a 500, and the reason is also written to the source row so a subscription that quietly stopped delivering is visible instead of inferred from a count that stopped moving.
skipped counts what could not be read. STIX patterning is a whole language; this imports simple equality on one property and refuses the rest rather than guessing — an indicator imported from the first clause of a compound pattern would match something real and wrong, which is worse than one that was never imported. A collection of four hundred compound patterns therefore reports "3 imported, 397 skipped" instead of looking like a collection with three indicators in it.
{ "sources", "enabled", "indicators", "healthy", "problems" } — one boolean a caller can act on rather than four fields each caller re-derives slightly differently.
Publishing
The sending half. Your organisation keeps collections of indicators it has chosen to share, and Threatera serves each one over TAXII 2.1 to the subscribers you name — an ISAC's members, a partner's TIP, another Threatera installation. Nothing is pushed anywhere: a subscriber pulls with a token you issued, and the platform serves what you put in the collection to the people you authorised.
revoked, which a well-behaved client acts on — Threatera's own does — but the copy is theirs. The screen says this before anything is sent, and the API makes the request say it too (irrevocable: true).What this organisation publishes: per collection its tlp, how many indicators are published and withdrawn, how many subscribers hold a live token and when one last pulled, and the api_root and url a subscriber configures. Readable by any member, for the reason the subscription list is: knowing what leaves your organisation is an assurance.
| Method & path | Description |
|---|---|
POST /api/collections | Create one: { "title", "description", "tlp", "name_publisher" }. Admin only. tlp marks every object in the collection and is fixed once created — re-marking what subscribers already hold is a statement about copies nobody here controls. name_publisher (default false) serves an identity naming your organisation and points every indicator at it; useful to a recipient, and a disclosure you may not intend. A new collection serves nobody until it has a subscriber. |
GET /api/collections/{id} | The collection, every indicator ever published into it — withdrawn ones included, with who withdrew them — and its subscribers (never their tokens). |
DELETE /api/collections/{id} | Stop serving it, to everyone. Admin only. Subscribers keep what they pulled and are not told: withdraw the indicators first if they should stop acting on them. |
Publish values: { "values": [{ "type", "value" }], "case_id", "irrevocable": true }, up to 500 per request. Analysts and above. Answers with what happened to every value — published, already (in the collection and not withdrawn) and refused, each refusal with its reason — so a publish that came out shorter than the selection does not read as everything having gone. "dry_run": true gives the same answer and writes nothing; it is what the screen shows before you confirm.
A value is refused unless all four hold, asked in this order:
| Question | Why |
|---|---|
It is a sha256, domain or ip | A file goes out by its SHA-256 alone — MD5 and SHA-1 of the same bytes would be three alerts for one event at every subscriber. URLs and email addresses are not offered: both can name a person. |
| Your organisation holds it | A file you have a submission of; an indicator you have a sighting of. The refusal is the same whether another customer holds it or nobody does. |
| The platform asserts it | A malicious or suspicious verdict, a public feed listing, or an analyst marking it malicious — the same rule as the STIX export and the block list, because every subscriber's SIEM will alert on it. An analyst here marking it benign, or a file a false positive, refuses it. |
| It may travel | Anything that arrived through a subscription under TLP:AMBER, AMBER+STRICT or RED may not leave your organisation at all; anything under GREEN may not go into a CLEAR collection. The refusal names the source. |
What a subscriber receives is the indicator and nothing behind it: the pattern, the value, the collection's marking and when it was published. Not the case it came from, not who published it, not why the platform asserts it.
curl -X POST "https://app.threatera.eu/api/collections/3/indicators" -H "x-api-key: $THREATERA_KEY" \
-H "Content-Type: application/json" \
-d '{"values":[{"type":"domain","value":"evil-c2.sbs"}],"irrevocable":true}'
| Method & path | Description |
|---|---|
DELETE /api/collections/{id}/indicators/{indicator_id} | Withdraw one. It is not deleted: it is served again as a new version with revoked: true, dated now, so a subscriber polling with added_after receives it like anything new. Publishing the same value again later is a new STIX object — STIX does not allow a revoked one to be revised. |
Issue a subscriber a token: { "name" }. Admin only. The response carries token (tts_…) once, with the api_root and collection url to hand over with it. One token per subscriber rather than an API key: a key grants a member's access, and a subscriber is not a member. Revoking one leaves the others working.
| Method & path | Description |
|---|---|
DELETE /api/collections/{id}/subscribers/{subscriber_id} | Revoke the token. Its next pull is refused with 401. What it pulled before, it keeps. |
Each pull is recorded: on the subscriber (last_pulled_at, pulls), and — when it served anything — in your audit log as taxii.pull by subscriber:<name>, with the range of what was served. An empty poll is not logged; it discloses nothing.
TAXII 2.1 discovery, and the rest of the server below it. This is what a subscriber's client calls, with the token you issued as Authorization: Bearer tts_… — or as the password of HTTP Basic, with any username, for clients that offer nothing else. Responses are application/taxii+json;version=2.1; a request for another TAXII version is refused with 406. Errors are TAXII error messages.
A token reaches one collection. Asking for any other — another organisation's, or one that does not exist — is the same 404. Read-only: nothing is accepted over TAXII.
| Method & path | Description |
|---|---|
GET /taxii2/api/ | The API root. |
GET /taxii2/api/collections/ | The collection this token reads, and no other. can_write is false. |
GET /taxii2/api/collections/{collection_id}/ | The same, by id. |
GET /taxii2/api/collections/{collection_id}/objects/ | Objects in date_added order: the collection's TLP marking-definition first (and its identity, if it names the publisher), then the indicators. Filters: added_after, match[id], match[type], match[version] (last, first, all or a timestamp), match[spec_version]. Paged with limit (default 100, at most 1000) and the opaque next; X-TAXII-Date-Added-First / -Last carry the range, and -Last is the cursor for the next poll. |
GET /taxii2/api/collections/{collection_id}/objects/{object_id}/ | One object. |
GET /taxii2/api/collections/{collection_id}/objects/{object_id}/versions/ | Its versions. Only the latest is held, so this is one entry. |
GET /taxii2/api/collections/{collection_id}/manifest/ | What objects/ would serve, without the objects. Same filters. |
curl "https://app.threatera.eu/taxii2/api/collections/COLLECTION/objects/?added_after=2026-10-01T00:00:00.000Z" \
-H "Authorization: Bearer tts_…" -H "Accept: application/taxii+json;version=2.1"
taxii, the api_root as its URL, the collection id, and the token as its secret with no username. Withdrawals arrive as revocations and are removed from the subscriber's intel on its next poll.Single sign-on
OpenID Connect, per organisation. A multi-tenant product cannot have "the" identity provider — each customer brings their own Entra ID, Okta, Google Workspace or Keycloak, and the point of SSO for them is that their directory decides who gets in and their policy decides what counts as authentication. Configuration is admin-only; the two sign-in endpoints are necessarily unauthenticated.
The redirect URI to register at the provider. Its own endpoint because it is the single most common thing to get wrong, and a mismatch produces a provider-side error that says nothing useful.
This organisation's providers. The client_secret is never returned — it authenticates this platform to the customer's IdP, and a value that can be read back is one that leaks.
Add a provider. The discovery document is fetched and checked before anything is stored, so a wrong issuer is found now rather than by the first person who tries to sign in.
curl -X POST "https://app.threatera.eu/api/sso/providers" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"name":"Acme Entra ID", "issuer":"https://login.microsoftonline.com/<tenant>/v2.0", "client_id":"…","client_secret":"…", "email_domains":["acme.example"]}'
| Field | Meaning |
|---|---|
email_domains | Required. How somebody typing their address at sign-in is routed here — sign-in happens before anyone is authenticated, so the address is the only thing available to route on. It is also re-checked against whatever the provider asserts: without that, an IdP configured for one customer could assert an address belonging to another and be believed. |
jit_enabled | Whether somebody the IdP authenticates, but who has no account here, gets one created. Off by default — on means every identity in the customer's directory can reach that organisation's intelligence. With it off, SSO authenticates people who were already invited. |
jit_role | What a provisioned account gets. read-only by default: an account created without a human deciding anything should not be able to change what the platform does. |
Update a provider. Omitting client_secret keeps the stored one — an admin editing the domain list should not have to re-enter a value they cannot read back.
Remove a provider. 204. Anyone who only ever signed in through it can no longer sign in at all: an account provisioned by the IdP has no password by construction, so invite them or re-add the provider.
Unauthenticated. Given {"email": "…"}, answers either {"sso": false} or an authorize_url — and nothing else. A chattier answer would let anybody enumerate which organisations use the product and which provider each one runs. false means "use the password form", not "that address does not exist".
The pending flow — state, nonce, PKCE verifier — is held server-side for ten minutes. Nothing about it is carried by, or forgeable from, the browser.
Where the provider sends the browser back. Redirects to the app with a session token in the URL fragment — a query string is written to every access log and proxy along the way and lands in the next request's Referer; a fragment is sent to no server at all. On failure it redirects to the sign-in screen with a readable reason.
Before any of that, the identity token must pass every check OpenID Connect asks for: signature against the provider's published JWKS, iss, aud, exp/iat, and the nonce from this specific sign-in. email_verified must be true — an IdP that lets somebody set an address without proving it would otherwise be an account-takeover primitive.
A domain routes nobody until it is verified. Listing acme.example on a provider claims it; it starts sending people to that provider only once a platform operator has confirmed the organisation owns it — by a DNS TXT record the organisation publishes, or a contract naming the domain. Without that, any organisation could list another's domain beside an identity provider it runs, and the sign-in screen would send that other organisation's staff to a login page of its choosing. GET /api/sso/providers returns verified_domains beside email_domains, so an admin can see which of theirs are live.
The provider speaks only for its own organisation's members. An address the provider asserts must belong to an account that is a member of the provider's organisation — or, with jit_enabled, becomes one. Holding the address is not enough: an account in another organisation, or a platform operator's account, is never signed in through a customer's identity provider.
Passwords still work. Enabling SSO does not disable them. An organisation can have SSO and members who predate it, and a sign-in screen that removes the only other way in is one that locks people out on the day their IdP breaks.
A provisioned account has no password at all — not a weak one and not a random one — and the forgot-password flow will not give it one: the customer's directory decides whether that person gets in, and a password would be a way round it. It also carries no platform MFA: the IdP performed authentication, including whatever second factor the customer's policy requires.
SAML is not implemented. Every provider worth integrating with speaks OIDC, and SAML is a second implementation with an XML signature stack behind it rather than a variation on this one. It is additive if procurement ever demands it.
ATT&CK coverage
Which MITRE ATT&CK techniques this organisation has actually seen, and which subsystem reported each one. Three parts of the platform already produce technique identifiers and none of them met: capa infers them from a binary's capabilities, Sigma rules carry them as tags, and the sandbox names them for behaviours no single API call demonstrates.
Techniques in the window, grouped by tactic. days defaults to 90.
| Field | Meaning |
|---|---|
sources | Which subsystems reported this technique — capa, sigma, sandbox. More than one is the interesting case: a technique both inferred from the file and observed running is a materially stronger claim than either alone, and it is why this is one view rather than three. |
name | The technique's name, or empty. capa ships the ATT&CK mapping with its rules so its names are used verbatim; a Sigma tag carries only an identifier. An id with no known name is returned bare rather than given an approximate one — a technique named wrongly is one somebody acts on. |
analysed / detonated | The denominator. "Four techniques" without it reads as a statement about the threat landscape rather than about how much has been looked at. |
truncated | The window held more rows than one call reads. The counts are a sample, not a total. |
curl "https://app.threatera.eu/api/attack/coverage?days=365" \ -H "x-api-key: $THREATERA_KEY"
Hunts
A retrohunt answers "does my corpus contain this?" once. A hunt asks the same question of everything that arrives from here on, and tells you when the answer changes. Any authenticated analyst can save one — writing a detection is the job, not an administrative act.
This organisation's saved hunts. Each carries last_run_at, how many files that run read, the running match_count, and last_error — a rule that has stopped compiling says so here rather than quietly matching nothing.
Save a hunt. The rule is compiled before it is stored, so a syntax error is a 400 now rather than a hunt that silently never fires.
curl -X POST "https://app.threatera.eu/api/hunts" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"name":"acme-loader","enabled":true, "source":"rule acme_loader { strings: $a = \"acme-c2\" condition: $a }", "include_existing":true}'
include_existing starts the watermark at the beginning rather than at now, so the hunt's first run also walks files you already hold. Off by default — that first run is the expensive one — but without it a newly saved hunt matches nothing until fresh samples arrive, which reads as a feature that does not work.
Hunts are created disabled unless you say otherwise: a rule saved half-written should not start alerting people because the next hour came round.
Run this hunt immediately instead of waiting for the hourly job. Returns { "scanned", "matched", "error" }.
It does exactly what the scheduled run does — same watermark, same one-alert-per-file rule — so triggering it by hand cannot produce a different answer from letting it happen. It exists because a rule you have just written is one you want to see the effect of, and "come back in an hour" is how somebody concludes the feature is broken.
A rule that no longer compiles returns 400 with YARA's own message, naming the line and the token.
What this hunt has caught, newest first — the file's SHA-256, which of the rule's names matched, and when.
A file is reported once per hunt, ever. A re-run over an overlapping window, a job retried after a crash, or the same bytes submitted again by another user cannot produce a second alert.
hunt.match event to whatever webhooks or syslog sinks the organisation has configured — see Event forwarding.Edit the name, the rule or the enabled flag. Editing does not rewind the watermark — re-reading everything the previous version already passed over is expensive and would re-alert on files it already reported. Delete and recreate to start clean.
Removes the hunt and its match history.
Data retention
How long each kind of data is kept. Every period is unset by default, and unset means indefinitely — nothing is ever removed until somebody chooses a number. A nightly job applies the policy; these endpoints only record the intention, and none of them deletes anything. Admin only.
scripts/apply_retention.py acts on it overnight on a connection the API does not have — so an authentication bug here cannot become data destruction, only a number a human sees on a screen before the next run.The current policy, every category with its own bounds and explanation, and pending — how many items each period would remove if the job ran now. A number of days means nothing until it is “and that is 4,182 files”.
| Category | Covers |
|---|---|
files_days | Samples, their static analysis and sandbox reports. The bulk of the disk. Bytes another organisation also holds are kept until that organisation's own policy releases them too. |
emails_days | Reported phishing, headers and bodies — usually the most personal data held here. The stored raw message goes with the row; attachments do not, since they are malware samples with their own analytical life, governed by files_days. |
urlscans_days | Recorded page fetches. Their screenshots are removed from object storage with them. |
watch_hits_days | Individual watchlist matches. The rules themselves are never removed. |
audit_days | Who did what. Cannot be set below 365 days — see the warning below. |
Set the periods. Send null for a category to keep it indefinitely; 0 is rejected rather than guessed at, because it is equally readable as “forever” and as “delete everything”.
curl -X PUT "https://app.threatera.eu/api/retention" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"files_days":180,"emails_days":90,"audit_days":730}'
Usage
What your organisation used, by month — the figures behind your invoice. Admin only: it is commercial information about the organisation rather than threat data, and the people working cases have no reason to see what the platform costs.
Your organisation’s monthly statements, newest first — admins only. One per month on a price plan, made once the month is over: the plan as it was when stated, the lines (the monthly fee, then for each measure what was used, what the plan included, how much is billable at unit_cents, the amount_cents and the basis the figure was measured on), the total_cents net of VAT, any notes (a measure that was never measured is charged nothing, and said), and voided_at / void_reason for one replaced by a corrected statement. A statement is what the invoice is drawn up from; it is not the invoice, which carries VAT and its own number. /document?format=pdf (default) or csv is one statement as a document; 404 for one that is not yours.
The operator’s price list — platform operators only, changes audited. A plan is a name, a currency, a monthly base_fee_cents and items: for each measure (detonations, urlscans, storage_gb, seats) the allowance included in the fee and the unit_cents charged per unit above it; a measure left out is not charged. archived: true takes a plan off the list offered for new organisations. A change applies to months stated afterwards only: each statement keeps a copy of the plan it was computed with. Assign a plan to an organisation with PATCH /api/tenants/{id} { "price_plan_id" } (0 clears it) or when converting a trial. Statements are generated by scripts/billing.py from a terminal, never by the API: that reads every organisation’s usage, which needs the database connection no request handler holds.
One month, defaulting to the current one. Pass ?month=2026-07 for a closed month. The end of the range is capped at today, so a month in progress reports the days that have actually happened.
| Field | What it is |
|---|---|
counters | detonations, urlscans, files_added, bytes_added — summed over the month. Recorded as each event happens, so retention deleting the underlying rows later does not change what the month says. A detonation counts when the sandbox slot is committed, since a run that failed still consumed one; a file that another team already submitted is not counted twice. |
gauges | bytes_stored and seats, each with peak, average, days_measured and days_in_range. These are levels rather than events — nobody uses 40 GB, they hold it — so they are sampled once a night. |
series | The raw (day, metric, value) rows, for charting. |
curl "https://app.threatera.eu/api/usage?month=2026-07" \ -H "x-api-key: $THREATERA_KEY"
average divides by days_measured, not by the length of the month. If the nightly sampler missed two nights, the month holds 29 measurements rather than 31, and averaging over 31 would report a storage figure lower than anything you ever actually held. Both counts are returned so the basis of the number is visible instead of assumed — an average over an unstated basis is the one figure nobody can check once the month is closed.Event forwarding
Everything else in this API flows inwards — feeds, TAXII, MISP, a reported-mail mailbox. This is the way out: findings pushed to a webhook, or to a SIEM over syslog in CEF. A SOC does not want a fourteenth console; it wants the finding in the queue it already watches. Admin only, and scoped to one organisation.
Every sink configured for this organisation, each carrying the result of its last delivery — last_status, last_error, failure_count. That is the answer to "is my SIEM actually getting these", which is otherwise indistinguishable from silence. failure_count resets on success, so it says is this broken now rather than has this ever broken.
The webhook signing secret is never returned here. It is shown once, at creation, for the same reason an API key is.
The events a sink may subscribe to. Deliberately a short, closed list — forwarding everything the platform does produces a firehose nobody subscribes to.
| Event | Fires when |
|---|---|
watchlist.hit | A watched value is seen. New hits only — a repeat sighting bumps a counter and is not an interruption, so re-analysing the same archive does not re-alert. |
case.created | An investigation is opened. |
case.status_changed | An investigation changes status. |
detonation.completed | A sandbox run finishes. Carries the persistence and indicator counts. |
file.malicious | A file is judged malicious. |
hunt.match | A saved hunt matches a newly arrived file. |
hindsight.found | A value your organisation met turned out to be harmful only later — a feed or one of your intel subscriptions published it, or this platform’s analysis first called the file harmful. Once per value. Carries kind, value, first_contact_at, known_at, known_by and dwell_seconds. |
federation.warning | A value your organisation contributed to early warning is now held by three or more organisations. Once per value. Carries kind, value and holders (a band). |
collector.silent | A collector has missed three check-ins. Once per silence — a collector that comes back and stops again fires again. Carries collector, host, last_seen_at and interval_seconds. |
An event goes only to the sinks of the organisation it happened in, chosen by that organisation explicitly rather than left to row-level security.
Add a sink. events may be omitted or empty, which means every event — what wiring up a SIEM usually means, and the alternative is ticking every box today and silently missing each event type added later.
curl -X POST "https://app.threatera.eu/api/event-sinks" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"kind":"webhook","name":"SOAR","url":"https://soar.example.com/hooks/threatera"}'
{ "id": 3, "kind": "webhook", "secret": "kQ8…", "events": [] }curl -X POST "https://app.threatera.eu/api/event-sinks" \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"kind":"syslog","name":"Splunk","host":"siem.example.com","port":514,"protocol":"udp","format":"cef"}'
refused and is not retried.Replace a sink's configuration. The signing secret is not rotated — changing the endpoint should not silently break every receiver that already verifies it.
Remove a sink. 204.
Queue a test event now. Without this, the first confirmation a sink works is the first real alert — the worst possible moment to find a typo'd port, and one that fails silently. The result lands on the sink; re-read it a few seconds later.
A webhook body is JSON, signed with the secret from creation:
x-threatera-event: watchlist.hit x-threatera-signature: t=1786368000,v1=9f86d081884c7d65…
Verify it as you would a Stripe signature. The timestamp is inside the signed material, not merely alongside it — signing the body alone leaves a captured request valid forever, and a replayed "case closed" is worth worrying about. Check the age first, then compare digests in constant time:
import hmac, hashlib, time
def verify(secret, body, header, tolerance=300):
parts = dict(p.split("=", 1) for p in header.split(","))
ts = int(parts["t"])
if abs(time.time() - ts) > tolerance: # reject replays first
return False
expected = hmac.new(secret.encode(), f"{ts}.".encode() + body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])The body is serialised with sorted keys and no whitespace, so a receiver that re-serialises to verify can reproduce the exact bytes that were signed.
CEF. A syslog sink emits RFC 3164 lines carrying a CEF payload, using CEF dictionary names where one exists (src, fname, fileHash, msg) so a rule written against src works across products. Values are escaped for both CEF layers — including newlines, since a raw one would end the syslog line and let a crafted indicator inject a second event into your SIEM.
CEF:0|Threatera|Threatera|1.0|watchlist.hit|A watched value was seen|8|msg=Watched value seen: evil.example cs1=evil.example cs1Label=value cs2=lookalike domain cs2Label=reason
Endpoint protection admin
Connect an organisation's own Microsoft Defender, CrowdStrike Falcon or Cortex XDR, so that what their endpoints blocked arrives here without anybody deciding to send it. Those files are exactly what cannot be uploaded to a shared service.
EDR_ENABLED is set. The API root passes the same SSRF guard intel subscriptions use, at poll time as well as at save time: a hostname that resolved publicly when it was configured can be repointed at a metadata service afterwards.| provider | status |
|---|---|
defender | Verified. A free Microsoft 365 developer tenant issues real credentials, so this connector is driven end to end against the real API. |
falcon | Written against documentation. CrowdStrike has no public sandbox; API access needs a customer or partner agreement. |
cortex | Written against documentation, for the same reason. |
Each source carries verified in its response, so nobody has to read that table to find out. "We support Falcon" is a claim that should carry its confidence with it rather than be discovered to be a guess by whoever tries it first.
| Method & path | Description |
|---|---|
GET /api/edr/sources | The EDR tenancies connected for this organisation. Readable by an organisation admin — whether their own endpoint protection is answering is their question about their own estate. last_error is the point of the row: "it has not worked since Tuesday" should be answerable here rather than from a worker's log. |
POST /api/edr/sources operator | Connect a tenancy. Body: { "name", "provider", "base_url", "client_id", "secret", "config", "enabled" }. Verified against the vendor before it is stored, and created disabled until it authenticates — an enabled source that has never worked is a job that fails every hour and teaches people to ignore the failure. config carries the non-secret provider-specific part: directory_id for Defender, api_key_id for Cortex. |
POST /api/edr/sources/{id}/check | Is it answering right now? Reports rather than fails: { "reachable", "detail" }, with the reason in plain words. Readable by an organisation admin. |
POST /api/edr/sources/{id}/poll | Poll now instead of waiting for the hourly job, and report what came back. check proves the credential authenticates, which is a smaller claim than "detections arrive" — somebody who has just connected a tenancy should not wait an hour to learn which of those they have. Reports rather than fails, and a paused source still polls when asked: pausing stops the schedule, not the person standing in front of it. |
PATCH /api/edr/sources/{id} | Pause or resume. Body: { "enabled" }. The two directions are not the same power. An organisation admin may pause — their EDR is their production estate and "stop calling it, now" cannot wait for a support ticket — but only an operator may resume, because enabling is the act that makes this platform call a customer's endpoints on a schedule. The cursor is untouched either way, so a paused source resumes where it stopped rather than skipping the gap. |
DELETE /api/edr/sources/{id} operator | Disconnect and forget the credential. The detections it produced are kept — they are a record of what the customer's endpoints blocked, and they did not stop being true because the connection was removed. |
GET /api/edr/detections | What this organisation's endpoints blocked, newest first: hash, filename, the device, the vendor's verdict, when. |
fetch_state says which happened — unsupported means the vendor will not return bytes, not that anything failed — and held says whether you actually have the sample here, which is the difference between knowing about something and having it. When bytes do arrive they go through the ordinary upload path, so deduplication, encryption, analysis, hunts and campaign clustering all happen exactly as for a file somebody dragged in.Trojan:Win32/Wacatac.B!ml is a claim by Microsoft; restating it as this platform's malicious would launder somebody else's finding into one of ours. The cursor also moves to the newest detection actually seen, never to now — the same rule the hunt watermark follows, because moving it to now skips whatever the vendor had not finished indexing when the poll ran.Campaign clusters
/similar answers "what looks like this file?" pairwise, on demand — a question somebody has to already be asking, about a file they have already opened. Clusters are the standing version: your corpus grouped nightly, kept, and reachable from a sample's own page.
7 samples, first seen 3 March until a person writes one.| signal | what it means | what it does |
|---|---|---|
imphash | identical PE import table — almost always the same toolchain | forms a cluster; the cluster's identity is the imphash |
typeref | identical set of .NET types imported — the managed counterpart, since every .NET program shares one imphash | forms a cluster, for a .NET program in place of its imphash |
tlsh | byte-level similarity within a conservative distance | attaches a sample; never merges two clusters |
behaviour | the latest sandbox runs did the same distinctive things (at least 80% alike, at least four shared) | attaches a sample; never merges two clusters |
infrastructure | a shared indicator that is rare in your corpus | attaches a sample; never merges two clusters |
seed | the earliest sample — what the others are linked to | not a link, and does not claim to be one |
Only the two exact signals form clusters, and that restriction is what makes the result usable. Transitive closure over a fuzzy threshold walks the corpus — A near B, B near C, C near D, and A and D end up three times the threshold apart in one group. On any real collection that becomes a single cluster of everything, which reads like a finding and is an artefact of the algorithm.
| Method & path | Description |
|---|---|
GET /api/clusters/map | Every campaign at once, for the map the Campaigns page shows before one is opened. clusters (id, name or null, members); nodes, one per sample with its cluster, latest verdict, filename and the signal that placed it (seed for the sample the campaign was grown from); edges, each membership's link to the sample it was attached to, with that signal. Campaigns of two or more that are not flagged too broad; memberships an analyst rejected are left out. At most 60 campaigns and 900 samples, largest first, with truncated saying when it stopped. |
GET /api/clusters | Your campaigns, largest first. ?ref=<sha256> narrows to the clusters containing one artefact — the lookup a sample's own page makes. ?include_broad=true adds the ones flagged as too large to be a campaign; they are off by default because listing real-but-useless groupings alongside the rest teaches people to ignore the list. |
GET /api/clusters/{id} | One cluster and the argument for every membership: signal, linked_to, reason. confirmed is null until somebody looks, true if an analyst agreed, false if they threw it out. families: the malware families the members’ own evidence names, each with how many members and how many of those were decoded. It describes the group and never formed it — two builds of one open-source RAT are not one campaign. |
GET /api/families | Every malware family your files are put under, most files first. A file is under a family when its own evidence names it — a decoded configuration, or a ClamAV signature or YARA rule naming it, as Which family reads it, without resemblance. Each with files, decoded, disputed (its evidence names another family as strongly), first_seen, last_seen and built_from for a fork. Read from your newest 2,000 analysed files (scanned, truncated). |
GET /api/families/{name} | One family as your organisation has met it, by its name or an alias in any case (asyncrat, Agent Tesla). files, newest first, with their evidence. configs: every decoded configuration of the family — from the file, a decoded layer or a sandbox run’s memory — in the order the builds arrived, with its c2, the settings a decoder names, a count of those it could not (unnamed, never compared) and changed: a new C2, one no longer called, a mutex or version that moved. c2: each C2 with how many builds carried it and when it was first and last seen. knowledge: your own knowledge page for it, if written. talk: how its builds talked in your sandbox — how many of its files have a run (runs), each TLS client (ja4) and plain-HTTP client (fingerprint, its headers and user_agents) with how many of its files used it, and every call-home schedule with whether it fits its configuration. infrastructure: its C2 servers that are one setup with others of yours, whatever their family — groups, each with its hosts, families and what was shared: an address they resolve to (your own DNS observations) or a certificate they presented (your real-internet runs; never the sandbox’s own). An address or certificate more than five of your names share is a shared host, listed in set_aside and never linked; addresses and networks give where each server resolves and its ASN, which never links. Nothing is looked up. 404 for a name that is not a family the platform knows. |
GET /api/clusters/{id}/reach | Where it landed here: the devices your endpoint protection blocked one of its samples on, and the people reported mail carrying one (attached, or inside an attached archive) or linking to its infrastructure was addressed to. Infrastructure is an indicator its samples hold that at most five other files here do. Each entry in reached has first, last, count and the evidence behind it; timeline is the same in time order. A membership an analyst rejected reaches nobody. coverage says what could be seen — EDR connections and reported mail, each with the date its record begins — because an empty answer without either is not “reached nobody”. |
GET /api/clusters/{id}/profile | Who is behind it, as your organisation has seen them — the adversary’s side only. lures: the reported mail that carried its samples — recent subjects, sender domains (never full addresses), kinds of attachment. timing: weekdays and UTC hours its mail was sent and its samples were blocked, once there are at least three. tooling: file types, decoded families, capability families, how many are packed or signed, behaviours most of its detonated samples share. Nothing about who received it, and no name until a person writes one. |
GET /api/clusters/{id}/lookalikes | Names and addresses here that look like this campaign’s infrastructure: suggestions to watch, never findings. Its habits are traits at least two of its own indicators share and at most 5% of your other indicators do — a top-level domain, a name shape (secure-login-2847 is a-a-9), a network from your own DNS observations, an address block, and where RDAP is on a registrar, nameserver or registration month — each with how many of its values carry it and how rare it is elsewhere. suggestions are indicators you sighted in the last 90 days matching habits of at least two kinds, each saying which and whether it is already watched. Nothing is stored, added to a case, a block list or a published collection, and nothing is looked up outside the platform. status: "too_little" with a reason when there is not enough to learn from. |
PATCH /api/clusters/{id} | Name it, or write down what it is. Body: { "name", "notes" }. Naming it also keeps it — a rebuild drops clusters it no longer produces, but never one somebody named. |
POST /api/clusters/{id}/members/{member_id}/decision | Agree or disagree with one membership. Body: { "confirmed": true | false | null }. false is not a delete: the membership stays, marked, so the nightly rebuild will not draw the link again and "somebody considered this and said no" survives. |
google.com are not related, and rarity is measured within your own corpus.Inbox
Everything waiting for a person, in one queue: watchlist alerts nobody has acknowledged, reported messages nobody has decided, and files the platform judged malicious or suspicious — or one of your hunts matched — that nobody has decided since. It is the question an analyst starting the day used to ask of three tabs separately.
Most urgent first: by severity, then by when the item became something to look at. Query: kind (alert, email or file; omit for all), claim (mine or unclaimed; omit for everyone's), limit (1–200, default 50), offset (up to 5000).
{
"total": 7,
"counts": { "alert": 2, "email": 1, "file": 4 },
"oldest": { "alert": "2026-09-30T08:01:00+00:00", "email": …, "file": … },
"results": [
{ "kind": "file", "id": "9f86d0…", "key": "file:9f86d0…",
"severity": "medium", "at": "2026-10-03T09:12:00+00:00",
"title": "invoice.exe",
"reasons": ["matched a hunt: loader-strings — after it was last decided"],
"claimed_by": "anna@example.com", "claimed_at": "…",
"facts": { … } }
]
}id is what that kind's own endpoints take: the hit id for an alert, the message id for an email, the SHA-256 for a file. reasons are sentences, every one still open on the item — a file the platform called malicious and a hunt matched is one item with two reasons, not two items. facts differs by kind. counts are per kind whatever kind asked for.
New evidence reopens a decision; repetition does not. A hunt matching a file after somebody decided it brings it back, with that said in its reason. Re-running the analysis that produced a verdict already answered does not. A severity of critical only ever comes from a watch rule somebody set to it: a platform verdict of malicious is high.
A reported message's own .eml and its attachments are files too, and are left to the message: one report, one decision. A member of an archive appears on its own only when a hunt matched it — otherwise its verdict already reached the archive it came in.
oldest is, per kind, since when the longest-waiting item has waited: an alert from its first sighting, a message from its arrival, a file from the evidence that put it here. It follows claim.
Say you are working an item, so the person next to you does not work it too. Your name shows on it for everybody. A claim never takes an item out of the queue — only acknowledging or deciding it does — and it is stored on the item itself, not beside it.
Taking over somebody else's claim is allowed: previous says whose it was, and the audit log records the takeover. A claim older than the item's last decision does not count, so a file a new hunt match brought back comes back unclaimed. 404 for an item your organisation does not have.
Let go of an item — yours, or an absent colleague's. 204. The audit log says whose it was.
Watchlist
Every other endpoint here answers a question you asked. A watch rule is a standing question the platform keeps asking on your behalf, and a hit is it interrupting you. Rules are checked on every ingest path — an indicator submitted, a file uploaded, a static analysis, a sandbox detonation, a URL scan, a reported email — and again against the public threat feeds after each nightly sync.
corp.local, so the rule would sit in the list looking like coverage and report nothing forever. Creation is the only moment anyone is paying attention.Everything your organisation is watching, noisiest first. Each rule carries hit_count, sighting_count and last_hit_at.
hit_count is distinct alerts — the same value turning up again in the same place refreshes the existing alert rather than opening another, so re-analysing one archive forty times does not report forty hits. sighting_count is every match, summed from each alert's times. The first answers “how many things matched”; the second answers “how noisy is this”.| Method & path | Description |
|---|---|
POST /api/watchlist | Watch a value. Body: { "kind", "pattern", "match_type", "label", "severity" }. match_type is optional and inferred from how the pattern is written. The response carries backfilled — how many matches were already in your data. |
PATCH /api/watchlist/{id} | Body: { "label", "severity", "enabled" }, all optional — relabel, reprioritise, or mute with "enabled": false. The kind and pattern are immutable — editing one would re-point every hit already recorded against the rule at a value that never produced them. |
DELETE /api/watchlist/{id} | Stop watching and discard the hits. Muting is what "this is too noisy" usually wants: it keeps the alerts and the record that somebody once cared about this value. |
GET /api/watchlist/kinds | The closed vocabularies, so a client never invents one. |
kind | pattern | Matches |
|---|---|---|
domain | acme.com | exactly that name |
domain | *.acme.com | that name and anything under it. Matching is on label boundaries, so evil-acme.com does not fire — which is the point, because that is exactly how a typosquat is built. |
ip | 50.16.16.211 | that address |
ip | 10.0.0.0/8 | any address in the range. 10.4.19.7/24 is accepted as the /24 it obviously means. |
hash | 32, 40 or 64 hex | MD5, SHA-1 or SHA-256. Files are stored by SHA-256, but static analysis computes all three — so a hash copied out of a vendor report works. |
email | ceo@acme.com | that sender address, for the impersonation a domain rule would miss. Watching the domain is a domain rule — it matches every reported sender there — so a wildcard such as *@evil.com is refused with that advice rather than stored as a rule that could never fire. |
url | https://raw.githubusercontent.com/actor/* | a URL indicator, exactly — or, with a trailing *, everything that starts with it, for an actor's whole repository on a host nobody could watch whole. |
family | Remcos | a malware family, by its name or an alias, in any case. Fires on a file whose own evidence names it — a decoded configuration (from the file or from what a sandbox run unpacked), or a signature or rule naming it — and, for a fork such as DcRAT, on the family it was built from too. A name the platform does not know as a family is refused with the list it does. |
ja4 | t13d3013h2_1d37bd780c83_8537cf56674e | a TLS client, as a sandbox run fingerprints it. Fires when another run’s sample speaks TLS with it — another build, same code. Refused unless it has a JA4’s shape. |
http_client | h_get11_04_08e7224bf8c7 | a plain-HTTP client shape, as network.http_clients writes it. Fires when another run’s sample asks that way. Both are checked against your runs already here when added. |
New rules are checked against what you already hold. Bounded to the most recent 2,000 indicators or files, and the count comes back as backfilled. Without it the first thing anyone does — test the rule against something they know they have — answers with silence, which reads as "it does not work". Only the new rule is checked: your other rules and their alerts are left exactly as they were.
Watch several values in one request — the shape a feed import produces, where fifty indicators land at once and all of them want watching.
{ "values": ["cdn-node.example.com", "203.0.113.42", "d41d8cd98f00b204e9800998ecf8427e"],
"severity": "high",
"label": "from the 14 Sep loader feed" }Values, not rules. The kind of each one is inferred, because a caller selecting rows in the indicator list has it already and should not restate it per value; send kind to override for the whole batch. Anything that cannot be placed confidently is refused by name rather than guessed at — storing a rule under a kind that can never match is the silence this feature exists to avoid. severity and label apply to every rule created.
rejected names each refusal with its reason — a URL, for instance, since only domain, ip, hash and email can be watched. That list is the part worth reading: a rule that looks like coverage and reports nothing forever is the failure the whole feature is built to prevent, and a bulk path that folded refusals into a count would be the fastest way yet to create fifty of them.Already watched is not an error here, unlike POST /watchlist's 409. In a batch it is the ordinary case — you select fifty and six are already watched — and refusing would mean working out which six before the other forty-four can be added. The same value sent twice in one request is added once. Capped at 500 values.
The backfill is one pass, not one per rule: bounded by the number of distinct kinds of thing to read rather than by the size of the selection, so hash reads files, ip reads IP indicators, and domain and email share the domain scan — three at the very most. Fifty bounded scans inside one POST is the timeout the bound was there to prevent.
{ "added": 44, "already": 5, "backfilled": 11,
"rejected": [ { "value": "http://example.com/gate.php",
"reason": "only domain, ip, hash, email can be watched — …" } ] }What the watchlist has seen, most recent first. Params: acknowledged (omit for everything, false for the open alerts), rule_id, severity, sort, limit, offset. Returns { "total": n, "results": [...] }.
sort is field:asc or field:desc over last_seen, first_seen, value, times, why (the rule's label), source_kind or severity — ranked, for the same reason as cases.
Each hit carries the value that actually matched — for a suffix or CIDR rule that is not the pattern, and 10.0.0.0/8 matched is not something anyone can act on — plus the rule's rule_label and severity, and an href into the UI.
source_kind | source_ref is |
|---|---|
file | the SHA-256 — from an upload, a static analysis, or a sandbox detonation |
ioc | the indicator value |
urlscan | the scan id |
email | the message id |
url | the URL indicator's id (URL indicators) |
feed | the feed key — or intel:<source name> for one of your own subscriptions. See below |
feed is the alert that could not have been a search. Every other hit fires because somebody did something. This one fires because the answer moved while nobody was looking: the nightly sync ran and a value you watch is now on a public blocklist. Finding that by searching requires knowing to search on the morning it became true.Your own TAXII/MISP subscriptions are swept by the same pass, and land in the same list with source_ref prefixed intel:. A CERT naming an address you watch is the same event as abuse.ch doing so — arguably a more urgent one, since it was sent to you specifically — and putting it in a second place to check is how it gets checked less. Only domain and ip are swept: a hash rule is matched at ingest, and no sweep can tell you a hash became bad.
Repeats bump rather than duplicate. The same (rule, source, value) updates last_seen and increments times. Re-analysing one archive full of watched domains produces one alert per value, not forty — which is the difference between a list people read and a list people mute.
Mark a hit as dealt with. Body: { "acknowledged": true }, or false to put it back — reversible on purpose. An alert cleared in a hurry and recognised an hour later as the start of something is ordinary, and a one-way control makes people hesitate before clearing anything, which is how a list stops being read at all.
Acknowledge — or reopen — several alerts at once. Clearing forty was forty round trips, which is the shape of work this list produces: a noisy rule fires on one afternoon's traffic and every hit needs the same answer.
Body: { "ids": [1, 2, 3], "acknowledged": true }. Capped at 500 ids.
{ "acknowledged": 37, "unchanged": 1, "missing": [41, 42] }
It reports what it did. acknowledged counts the rows
actually changed, unchanged those already in that state (a
repeat request is safe and says so), and missing names ids that
were not your organisation's to touch.
{ "open_hits": n, "active_rules": n } — what the badge in the navigation shows. Cheap enough to call on every page load: it is answered by a partial index over unacknowledged hits only.
Mail. A tenant owner can set an alert address under Tenant settings (PATCH /api/tenants/{id}, field alert_email). A daily job then sends one digest per organisation of the hits nobody has acknowledged. It is NULL by default, so an installation with a mail server configured still sends nothing to anyone who did not ask; and it is one address per organisation rather than one per user, because an alert belongs to a team list that outlives whoever wrote the rule.
Reported email
Phishing reports — from a mailbox the platform polls, or uploaded one at a time. An email is analysed as an archive of one: the raw .eml is stored as an ordinary file and each attachment is stored with extracted_from set to the message's hash, exactly as a zip's members are. Attachments therefore appear in /api/files with the same dedup, retention, detonation and deletion as any upload.
unknown, never as a pass.Reported messages, newest first. Params: verdict, q (matches subject, sender or Reply-To), since (received here at or after, ISO — never the message's own Date header, which its sender wrote), sort, limit, offset. Returns { "total": n, "results": [...] }.
sort is field:asc or field:desc over received_at, sent_at, subject, from_address or verdict — ranked, worst first: as plain text clean sorts before malicious, which is the exact inverse of what somebody working a phishing queue is looking for.
Each row also carries analyst_verdict, analyst_note, decided_by and decided_at — what a person concluded, beside the derived verdict. Null means nobody has looked. Written by PUT /email/messages/verdict.
collector names the collector that sent the message in (threatera watch); null when a person reported or uploaded it.
Which of your campaigns this message looks like, and why — a suggestion, never an assignment. Compared with each campaign’s adversary profile (newest first, up to sixty, not the over-broad ones): the same sender domain, a subject worded like its lures, the same kind of attachment, its usual sending hour. A match needs a shared sender domain or lure and one more reason, each listed in reasons; already: true when the message carried one of the campaign’s own samples. Attaching a sample to a campaign stays the analyst’s act.
One message with everything the analysis produced:
| Field | Meaning |
|---|---|
auth | { "spf", "dkim", "dmarc" } as the receiving server recorded them. A key is absent when the header did not state it. |
findings | Why the verdict was reached — each with id, severity, title and detail. A mismatched Reply-To, a display name claiming a brand its address does not, a link whose text and target disagree, a lookalike sender domain. |
attachments | Stored files, by hash — open them under /api/files/{hash}, where provenance.extracted_from points back at this message. |
urls | Every link found. They are not fetched: a phishing message is mostly tracking pixels, and opening one confirms delivery. Scanning one is a deliberate POST /api/urlscan. |
qr | The text of every QR code in the message — read from its image parts, inline ones included, and from images written into the HTML; a remote image is not fetched. A code that opens a web link is also in urls, and raises a medium finding, qr-link. |
indicators | The hosts recorded as indicators — the sender's domain, the reply path, and every link host. Each has a page under /api/iocs/{value} with its sightings and feed matches, which is what makes a report a starting point rather than a dead end. A host whose TLD is unrecognised never became an indicator and is absent, so a client can link exactly what exists. |
eml_hash | The raw message, downloadable as a file. |
Record the same conclusion about several reported messages at once. Body: { "ids": [...], "verdict", "note" }, where verdict is one of confirmed, false_positive, benign, needs_work — or null to withdraw the decision and return the messages to “nobody has looked”.
verdict on the message is derived from SPF, DKIM, DMARC and the header findings: re-analysis must be free to move it, and it is left alone here. What this writes is analyst_verdict, beside it, with analyst_note, decided_by and decided_at — all four returned by the list and detail endpoints. analyst_verdict: null means nobody has looked, which is not a verdict of unknown and is never backfilled.A reporting mailbox produces the most repetitive queue in the product: forty people forward one campaign inside an hour and every one of them gets the same answer. The note is therefore checked once against the batch — a reason good enough for forty messages is a reason, and asking forty times is how somebody types “fp” forty times. It is required to clear something the headers called malicious or suspicious, exactly as PUT /files/verdict requires it.
Reports what it did rather than that it succeeded: decided counts the rows written and missing names the ids that were not yours to touch. Capped at 500 ids.
{ "decided": 37, "missing": [418, 419, 420] }Analyse a .eml or an Outlook .msg directly — multipart/form-data with a file part, no mailbox involved. Returns the same shape as the detail endpoint above.
A .msg is read from what Outlook kept: a received message’s original headers (its transport headers, so authentication results and spoofing findings work), its bodies and its attachments. One saved without transport headers — a draft, an item from Sent — carries a saved-without-headers finding, and its SPF, DKIM and DMARC read as unknown, never as passed. The file is stored as uploaded.
409 if this organisation has already analysed a message with the same Message-ID. Available whether or not mailbox polling is enabled: the switch governs automatic collection, not a file an analyst chose to submit.
Optional form field collector: the name of the collector sending it. The message is named on its row, counted on the collector (messages_sent), and starts Autopilot under the organisation’s switch for collected material rather than for reported mail. A send-only collector key may call this, under its own name only, and gets back { "id", "accepted": true } — never the analysis.
This organisation's reporting mailbox, plus ingest_enabled — the installation-wide switch, so a client can distinguish "configured" from "configured and never polled".
has_password reports only whether one is set. Reading reports is an ordinary analyst action, but configuring the mailbox is not: it stores a credential to a system Threatera does not operate, and it starts collecting personal data about people outside your organisation. See §7 of the privacy policy.| Method & path | Description |
|---|---|
PUT /api/email/mailbox admin | Create or replace it. Body: { "host", "port", "username", "password", "use_ssl", "folder", "enabled" }. Omit password to keep the stored one; enabled: true without any password is refused rather than failing silently at the next poll. |
POST /api/email/mailbox/test admin | Connect, log in and open the folder. Ingests nothing and marks nothing seen. Returns { "ok": true, "messages_in_folder": n } or { "ok": false, "error": "…" }. |
DELETE /api/email/mailbox admin | Remove the mailbox and its stored credential. Messages already analysed are kept — disconnecting a mailbox is not a request to erase its history. |
400 when saved, and again at every connection — the socket is opened to the address that was checked, never to the name resolved a second time. With use_ssl, the server's certificate is verified against the public trust store and the host you entered, so a self-signed certificate fails the test with the TLS error rather than being trusted with the password. Every read times out after 20 seconds; the test gives up after 30 in all, and one mailbox's poll after five minutes. A poll that is cut short keeps the messages it had already fetched and records why.Polling is a scheduled job (k8s/mailbox-poll-cronjob.yaml, every 15 minutes), not a request you make. Messages are marked \Seen and left in the mailbox; nothing is deleted and no reply is ever sent.
YARA rules
Manage the YARA ruleset used during analysis at runtime — no redeploy needed. Enabled rules are picked up by the next analysis.
Turn several detection rules on or off in one request, across all three engines — pushing a set live, or silencing a family that has started firing on everything. Each rule is named by its engine and the same reference its own route takes:
{ "rules": [ { "engine": "yara", "ref": "YARAForge:APT28_Downloader" },
{ "engine": "sigma", "ref": "susp_office_macro_autoopen" },
{ "engine": "hunt", "ref": "14" } ],
"enabled": false }engine is yara, sigma or hunt; anything else is a 400. ref is the rule name for yara and sigma and the id for a hunt. Capped at 500 rules.
enabled there is not yours to write: one customer silencing a noisy YARA-Forge family would silence it for all of them. The mute is a row your organisation owns, the rule is untouched, and it survives the next rule-feed sync. changed is rules actually switched; muted is platform rules silenced for you alone. Being told "40 disabled" when 31 of them were muted for your organisation would be a lie about what you changed.Already in the requested state is not counted as a change, so a repeated request is safe and says so. missing names references that were not yours to touch — a rule belonging to another customer and one that does not exist are the same non-match under row-level security.
{ "changed": 2, "muted": 31, "unchanged": 1, "missing": ["yara:no_such_rule"] }List all rules (without source). Each carries name, enabled, created_at, platform and source_feed. Related operations:
| Method & path | Description |
|---|---|
POST /api/yara-rules | Add a rule (source must compile, name unique). Body: { "name", "source", "enabled" } — enabled defaults to true. The name is the rule's address in every route below, so it may contain a / (platform Sigma titles do) but not one at either end, a //, a . or .. segment, a control character, or more than 200 characters — the parts a proxy or client may rewrite before the request arrives, which would leave a rule its own URL cannot reach (400). |
GET /api/yara-rules/{name} | Get one rule, including its source, with source_lines and rule_count describing all of it. Optional max_lines bounds the source returned, and source_truncated says whether it was cut — ask for a preview when you only need to show a rule: one platform rule can be a whole feed (YARA-Forge core is 5,141 rules in 7.9 MB). Never save back a truncated source; it would replace the rule with its first lines. |
PUT /api/yara-rules/{name} | Replace one of your own rules' source. Body: { "source" }; it must compile (400 otherwise). 403 on a platform rule — save your version under your own name instead. |
PATCH /api/yara-rules/{name} | Turn a rule on or off. Body: { "enabled": true|false }. For a platform rule this mutes it for your organisation — see below. |
DELETE /api/yara-rules/{name} | Delete one of your own rules. 403 on a platform rule. |
Your rules and the installation's
platform: true marks a rule this installation provides — the two examples a fresh install ships, and everything imported from a rule feed (source_feed names which). One row is shared by every organisation and belongs to none of them.
| On a platform rule | What happens |
|---|---|
a PATCH of {"enabled": false} | Mutes it for your organisation only. The mute is a row you own; the shared rule is untouched and survives the next rule-feed sync. Sending true unmutes. Needs an X-Tenant header when your token could act for more than one organisation — muting happens inside one, and there is no installation-wide answer to give. |
a DELETE | 403, with an answer that says what to do instead. Deleting it would remove it for every customer on the installation. |
a PUT | 403. The row is every organisation's, and the next rule-feed sync would overwrite an edit anyway. |
enabled means "in force for you", not the stored column. A platform rule you have muted comes back enabled: false even though it is still on for everyone else — reporting the raw column would tell you a rule is running when you switched it off.DELETE a platform rule and it vanished for every organisation on the installation — Postgres consults only a policy's USING clause for a DELETE, and that clause admits the shared rows so they can be read. The migration splits read from write; the 403 refuses it a layer earlier.Run a Sigma rule over your past sandbox runs and say which it would have matched. A saved Sigma rule applies to runs from then on; this rebuilds the events of the newest limit (default 300, at most 1000) of your completed runs and matches the rule against them. Body: { "source", "limit" }. Returns scanned of of, matched_runs and up to 100 matches (run, file, how many events). Nothing is written.
A rule’s regular expressions run in a short-lived process of their own, under the per-run time limit the sandbox worker uses: a run the rule took too long on is skipped and counted in overran, and stopped says the whole hunt reached its limit before every run was read. 400 for a rule this engine cannot evaluate.
Scan already-stored files with a YARA rule and return the matches. Validates the rule compiles, then scans up to limit (max 1000) of the most recently ingested files.
curl -X POST https://app.threatera.eu/api/retrohunt \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"source":"rule x { strings: $a = \"evil\" condition: $a }","limit":500}'
Sigma rules
Where YARA matches what a sample is (its bytes), Sigma matches what it does. Sigma rules are evaluated against sandbox telemetry after every file detonation, and matches appear on the detonation record under sigma.
List all rules with their source, enabled state, and the title / level parsed out of the rule itself. ?with_source=false leaves source null — for a listing that shows names and levels, since the platform's own rules alone are over a megabyte of YAML. Related operations:
| Method & path | Description |
|---|---|
POST /api/sigma-rules | Add a rule. Body: { "name", "source", "enabled"? }. 400 if the rule is invalid or unsupported or the name could not be addressed (the same rules as for YARA), 409 if the name is taken. |
GET /api/sigma-rules/{name} | Get one rule, including its source. |
PUT /api/sigma-rules/{name} | Replace one of your own rules' source. Body: { "source" }, checked as a new rule is (400 if invalid or unsupported). 403 on a platform rule. |
PATCH /api/sigma-rules/{name} | Turn a rule on or off. Body: { "enabled": true|false }. For a platform rule this mutes it for your organisation only. |
DELETE /api/sigma-rules/{name} | Delete one of your own rules. 403 on a platform rule. |
Rules also carry platform and source_feed, and the platform-rule rules are identical to YARA's — see there for why a shared rule is muted rather than disabled, and why enabled reports what is in force for you rather than the stored column.
curl -X POST https://app.threatera.eu/api/sigma-rules \ -H "x-api-key: $THREATERA_KEY" -H "content-type: application/json" \ -d '{"name":"beacon_over_tls","source":"title: Sample beaconed over TLS\nlevel: high\nlogsource:\n category: network_connection\ndetection:\n sel:\n DestinationPort: 443\n condition: sel"}'
unsupported field modifier 'utf16le' in 'sel' — rather than being stored as enabled and silently never firing.What a rule can match on
After a detonation, the sample's telemetry is converted into events using the standard Sysmon/Sigma field names, and every enabled rule is evaluated against them. Scope a rule to one kind of event with logsource.category. Matches are returned on the detonation record (GET /detonations/{id}) under sigma.
Event categories & fields
| Category | Fields |
|---|---|
process_creation | Image, CommandLine, ExitCode, Stdout, Stderr |
dns_query | QueryName |
network_connection | DestinationIp, DestinationPort, DestinationHostname, Initiated |
http_request | Request |
file_event | TargetFilename, Sha256, FileType, ChangeKind |
Supported rule syntax
| Feature | Supported |
|---|---|
| Value modifiers | contains, startswith, endswith, re, all, cased. Matching is case-insensitive unless cased; for re that is a flag, so the pattern's escapes keep their meaning. A re pattern that does not compile is refused when the rule is saved, and each rule gets 5 seconds per sandbox run (SIGMA_RULE_TIMEOUT_SECONDS) — one that runs out is reported on the run as stopped, never as having matched nothing. |
| Conditions | sel, a and not b, 1 of sel_*, all of them, and any of those combined: selection and not 1 of filter_* |
| Values | Strings (with * / ? wildcards), numbers, and lists (OR-combined) |
Matching is case-insensitive unless the field carries |cased.
{
"sigma": [{
"rule": "beacon_over_tls", "title": "Sample beaconed over TLS",
"level": "high", "matches": 2,
"events": [{"category":"network_connection","DestinationHostname":"example.com","DestinationPort":443}]
}]
}A stored rule that later fails to parse is reported per-rule as { "rule": …, "error": … } instead of failing the whole detonation.
Insights
The static PE heuristics, measured against your analysts. Every analysis of a PE now records heuristics: named findings in five families — injection (writing into another process and starting code there), packing, memory (writable and executable code in an unpacked file), capture (keystrokes or the active window), signature (data appended after a signature block) — and would_raise, true when two unrelated families are present. They are report-only: no verdict changes.
This endpoint is the measurement that decides whether they should. It evaluates the rules as they are now over this organisation's most recent 2,000 PE files, from the parsed PE each analysis already stored — so files analysed before the rules existed are covered — and returns by_analyst: for each conclusion (confirmed, false_positive, benign, needs_work, undecided) how many they would raise and how many they leave quiet, plus per-family counts, fired_signed, and up to ten examples per conclusion to open and read. The rows that matter are false_positive and benign.
fired_signed is there so the measurement can show how much of what fires is signed software — the evidence an exemption would need once signatures are checked.The lure readers' findings, measured against your analysts. The PDF, page, Office, .NET, batch, PyInstaller and QR readings, the decryption of encrypted Office files and the reading of Outlook messages add findings — a PDF that starts a program, a page that asks for a password or builds a file, a remote template, the Follina shape, DDE, Excel 4.0 macros, a known exploit object, an obfuscator's marker, a batch file hiding what it runs, an Office file encrypted with a password Office applies without asking (or one a lure gives, or one nothing opened), an Outlook message carrying files — and most are report-only. Those marked "raises": true raise a file's verdict to suspicious, never further: a PDF that starts a program, a smuggled file, the Follina shape, DDE, Excel 4.0 macros that run on open, a known exploit object, an Office file encrypted with a password Office applies unasked, and a file opened with its message's password or the one malware is shared under. An analysis lists the ones that fired as raised_by.
This is the count that decides whether one should move a verdict, on the pattern of /api/heuristics/agreement: over this organisation's most recent 2,000 files any reader read, findings lists each finding with read (files its reader saw), fired, by_analyst (confirmed, false_positive, benign, needs_work, undecided) and up to five cleared files it fired on, to open. read_by counts each reader's files: a file analysed before a reader existed has no reading and is not counted, so a finding that has never fired can be told apart from one that has never looked.
What needs attention, then what the volumes look like. The two lists it leads with are open cases and unacknowledged watchlist hits — the question somebody opening a dashboard actually has. Totals and breakdowns follow.
{
"totals": {"files":24,"iocs":281,"urlscans":31,"detonations":93,
"yara_rules":4,"sigma_rules":11,"open_cases":3,"closed_without_review":1,"open_alerts":7},
"open_cases": [{"id":14,"reference":"CASE-2026-014","title":"…",
"severity":"high","status":"open", … }],
"open_alerts": [{"id":88,"value":"login.acme-sso.com","source_kind":"urlscan",
"severity":"high","why":"our domains","last_seen":"…"}],
"verdicts": {"undetected":19,"malicious":3,"suspicious":2,"unknown":2},
"ioc_types": {"domain":244,"ip":36},
"new_files_daily": [{"date":"2026-07-20","count":3}],
"new_email_daily": [{"date":"2026-07-20","count":1}],
"top_iocs": [ … ],
"regulatory": {"available":true,
"summary":{"open":2,"overdue":1,"hours_to_next":-3.2,
"cases":2,"unanchored":1},
"stages":[{"case_id":14,"reference":"CASE-2026-014",
"framework":"nis2","label":"Early warning",
"hours_remaining":-3.2, … }]},
"week_start": "2026-09-28T00:00:00+00:00",
"search_available": true
}week_start is the start of the window every _7d figure and the last seven daily buckets cover — midnight UTC six days ago, one window for all of them. Each list the dashboard links to takes it back as a filter (new_since on files and indicators, since on reported mail, sandbox runs and URL scans), so a tile and the list it opens count the same things. sandbox_7d counts the runs the sandbox list shows: dismissed runs are left out of both.
open_cases and open_alerts appear twice on purpose: as a count in totals, and as the first few rows. The lists are capped at six each — the totals are not, so a badge and a list can disagree about length without either being wrong. A case row also carries assignee, updated_at and item_count.
totals.closed_without_review counts closed cases nobody has written a post-incident review for, across all time. A count rather than a gate: a case may close before its review, so this is what stays on screen until somebody writes it.
Cases are ordered by severity explicitly, not as a string: alphabetically critical sorts before low, so a naive sort looks right and is wrong at exactly the moment it matters. monitoring counts as open — actions taken, watching for recurrence, still somebody's work.
top_files answered "what is biggest", and the biggest thing in a corpus is almost always the benign installer somebody uploads twice a week. totals.analyses counted internal jobs — one per deep upload, so it was a second, noisier copy of the file count. Both are gone from this response; top_iocs stays, and /api/stats still reports analyses.regulatory is the statutory clock, across every open case. The worst five stages plus a summary; the full list is GET /api/regulatory/due. It is guarded the same way the search half is, and for a stronger reason: available: false means the lookup failed, and an empty stages list must not be drawn as "nothing due" when nobody actually asked. summary.unanchored counts open cases with a framework selected and no awareness time recorded — no clock running at all, which is the quietest way to miss a deadline.search_available tells you whether the empty ones are really empty. Four of these fields — verdicts, ioc_types, new_files_daily, top_iocs — are read from the search index; everything else comes from the primary database. If the index is unavailable this response still returns 200 with the database half intact, those four empty, and search_available: false. Do not plot them as zero when it is false: an empty verdict breakdown renders as a clean corpus, which is a confident wrong answer rather than a missing one. The search endpoints answer 503 in the same situation, because unlike this one they have nothing to fall back on.new_email_daily is bucketed on when the platform received the report, not on the message's own Date: header — a forwarded report of a March mail would otherwise land in March and never appear in a 14-day chart, and a header date is attacker-controlled anyway. Both daily series fill gaps with zero, so a client can plot them without reindexing.
Lightweight overview counts: { "files", "iocs", "analyses", "yara_rules", "sigma_rules" }. Every one of them is counted from the per-organisation tables, never the global ones — a count taken from the shared corpus would report every other customer's volume to you.
The nodes and edges around a file or an indicator, for a relationship view. Walks the links the platform already holds: indicators extracted from files, indicators contacted by URL scans, and observed domain → IP resolutions.
Query parameters
| Name | Type | Description |
|---|---|---|
| value required | string | The seed: a SHA-256, or an indicator value. |
| depth | integer | Hops to expand from the seed. 1 (default) or 2. |
{
"nodes": [
{"id":"file:8d0a…a255", "type":"file", "label":"8d0aa1b2c3d4…", "hash":"8d0a…a255"},
{"id":"domain:evil-c2.com","type":"domain", "label":"evil-c2.com", "value":"evil-c2.com"},
{"id":"ip:93.184.216.34", "type":"ip", "label":"93.184.216.34", "value":"93.184.216.34"}
],
"edges": [
{"source":"file:8d0a…a255", "target":"domain:evil-c2.com", "kind":"extracted"},
{"source":"domain:evil-c2.com","target":"ip:93.184.216.34", "kind":"resolved"}
]
}Node ids are type-prefixed (file:, domain:, ip:, urlscan:) so a domain and a file can never collide; label is the display form (file labels are the truncated hash). Edge kind is one of:
kind | Meaning |
|---|---|
extracted | The indicator was extracted from that file. |
contacted | A URL scan contacted that indicator. |
resolved | The domain was observed resolving to that IP. |
Edges are undirected for drawing purposes and de-duplicated, so expanding a domain and then its IP won't emit the same resolution twice. 404 if the seed matches nothing.
The public threat feeds this installation ingests — how many indicators each holds, when it last synced, and whether it is stale.
Readable by any authenticated user. A feed match is what the platform asserts about an indicator, so an analyst weighing that assertion needs to know which sources back it and how current they are. Nothing here is tenant-specific: the corpus is identical for every organisation.
{
"enabled": true, "stale_after_hours": 48,
"healthy": false,
"problems": [{"feed":"urlhaus","health":"stale",
"detail":"stale","stale_since":"2026-08-03T19:42:32Z"}],
"feeds": [{"key":"urlhaus","name":"URLhaus","health":"stale","stale":true,
"indicators":412031,"last_sync":"…","status":"ok","error":null,
"licence":"CC0","homepage":"https://urlhaus.abuse.ch/"}]
}healthy is one boolean a caller can act on rather than four fields each caller re-derives slightly differently: false whenever the subsystem is off, holds no feeds, or any feed is not answering for itself. problems is the same set, spelled out. Per feed, status is what the last sync run reported and health is the judgement about the feed now — a run that finished cleanly two weeks ago is status: "ok" and health: "stale", and the second one is the one to act on.
health | detail says |
|---|---|
ok | —; the feed is not listed in problems at all |
never-synced | has never synced — run scripts/sync_feeds.py. The failure this whole subsystem exists to avoid: a corpus that never synced answers "not in any feed" for everything, with total confidence, and reads exactly like a genuinely clean indicator |
stale | the literal string stale, with the instant in a separate stale_since field |
error | the sync error, or last sync failed |
empty | synced but holds no indicators |
stale_since is a separate field because it is a timestamp, not prose. Interpolating it into detail rendered "last synced 2026-08-03T19:42:32.452553+00:00" beside a table showing the same instant as "8/3/2026, 9:42:32 PM" — two spellings of one fact, one of them unreadable. The client formats it the way it formats every other time.Matches appear on the indicator itself, under enrichment.feeds in GET /api/iocs/{value} — each entry naming the feed, what it calls the threat, a confidence where the source publishes one, and a link back to the source's own page.
counter, first_seen, last_seen) are what your organisation encountered. A feed match is what public research says about the same value. They are kept apart deliberately — merging them would tell you that you saw something you never did.Ingestion is inbound only: the platform downloads the same files every other subscriber gets, on a schedule unrelated to anything you submitted. Nothing about your samples leaves. That is why this is on by default while per-lookup enrichment such as RDAP is not — a lookup query would reveal what you are investigating.
Sources: URLhaus, ThreatFox and Feodo Tracker (abuse.ch, CC0) and the Tor Project's exit list.
Curated detection rulesets this installation imports — how many rules each holds, when it was last refreshed, and whether it is stale. A fresh install ships two example YARA rules; the import adds roughly five thousand.
Readable by any authenticated user, for the same reason /api/feeds is: this is what the platform asserts it can detect, and an analyst reading a clean verdict deserves to know whether the ruleset behind it was refreshed on Tuesday or never.
Each package is imported as one platform-provided rule rather than one rule per detection: the file carries import "pe" / "dotnet" / "hash" and a few rules whose condition references another by name, and splitting it breaks both.
Source: YARA-Forge core package (community YARA rules, deduplicated and licence-filtered upstream). There is deliberately no Sigma feed — of SigmaHQ's 1,377 core rules, 0 use only the event fields this Linux sandbox produces, so importing it would show coverage that cannot fire.
Server-side limits a client should respect before uploading: { "max_upload_size_mb": 100 }.
Read this rather than hard-coding a number — it lets you reject an oversized file instantly instead of streaming it only to be 413'd, and it makes the effective limit visible when debugging a deployment whose config differs from the default.
Active platform announcements (maintenance windows, notices), newest first — visible to every authenticated user.
| Method & path | Description |
|---|---|
POST /api/announcements operator | Post an announcement. Body: { "message", "level": "info"|"warning"|"critical" }. Platform operators only: announcements are installation-wide, shown to every user of every organisation, so there is no such thing as one addressed to your own. |
DELETE /api/announcements/{id} operator | Remove an announcement. |
Account
Session and self-service endpoints used by the web UI.
| Method & path | Description |
|---|---|
POST /api/auth/login | Exchange email + password (plus the TOTP code, once enrolled) for a JWT access token. Body: { "username", "password", "otp"?, "device"? }. A completed sign-in also returns device_token; send it back as device on the next login from the same client and that client spends a rate-limit budget of its own for the account, so somebody hammering the account — or the whole endpoint — cannot lock you out. It grants a budget and never access, and a password change retires it. |
POST /api/auth/accept-invite | Join the organisation an invitation names, as the account you are signed in as. Body: { "token" }. How an existing account joins another organisation. A signed-in session, not an API key; the invitation must have been sent to this account's address (403 otherwise — a forwarded link joins nobody); single use and expiring like registration (400). 409 if you are already a member. Returns { "tid", "slug", "name", "role" } — send the tid as X-Tenant to act there. |
POST /api/auth/register | Accept an invite and set a password. Body: { "token", "password" }. The token comes from the invitation mail — the only other way an account comes into existence is a self-service trial (below), where an installation offers one. A username is accepted and ignored: the address the invitation was sent to becomes the username, or an invite to one person could be redeemed as another. 409 if that address already has an account: sign in and use /api/auth/accept-invite instead. |
GET /api/auth/me | Return the current principal (from the JWT or the service key). |
POST /api/auth/change-password | Change your own password. Body: { "current_password", "new_password" }. The current one is required even though you are already authenticated — it is what makes a stolen session unable to lock the owner out. Clears a pending require-password-change. Ends every session the account has, this one included, and returns a fresh access_token for the caller to continue with — the server cannot tell which session is yours, and a change that left the others working would not evict whoever prompted it. |
GET /api/auth/signup | Whether this installation lets people start a trial themselves (available) and for how many days (trial_days). Signed out. Off unless the operator switches it on (SELF_SIGNUP_ENABLED) and mail works. |
POST /api/auth/signup | Start a trial. Body: { "email", "organisation" }. Always 202 and equally fast, whether or not the address has an account: the address gets one mail — a link to confirm, or a note that it already has an account — and nothing is created until the link is used. An installation accepts a limited number of new trials a day. 404 where trials are not offered. |
GET /api/auth/signup/pending | What a confirmation link is for: ?token= → email, organisation, trial_days. 400 for a link used or expired. |
POST /api/auth/signup/complete | Confirm a trial. Body: { "token", "password" }. Creates the organisation — a trial of TRIAL_DAYS days with the trial quotas — the account (the lowest global role, as for an invitation) as its owner, and loads the demo corpus: harmless files and made-up messages, marked as demo, through the real pipeline. Signs in; second-factor enrolment follows. 400 for a used or expired link or an address that already has an account. |
GET /api/trial | Whether your organisation is a trial (trial), when it ends (ends_at, days_left, ended) and whether the demo corpus is in it (demo). Once a trial has ended, everything in it can still be read and nothing new can be added (413, X-Quota-Exceeded: trial). demo is answered for every organisation: a converted trial keeps its demo data until an admin removes it. |
DELETE /api/demo | Remove the demo data your organisation started with — admins only, audited, not undoable. The demo files and messages are recognised by what they are (the two files' SHA-256, the three messages' Message-IDs), never by the demo tag or a subject a customer could also write. Takes them and what the platform made of them: analyses, sandbox runs and the files a run saw written, Autopilot dossiers, hunt and watchlist hits, campaign memberships, and indicator sightings nothing else of yours still shows. Anything in a case stays. Returns files, messages, investigations, indicators and how many items a case kept; state is none when there was nothing to remove. |
POST /api/auth/forgot-password | Email yourself a reset link. Body: { "username" }. Always 202, whether or not the account exists — anything else would let an unauthenticated caller enumerate who has an account here — and equally fast: the link is issued and mailed after the response has been sent, so the time taken says nothing either. /auth/login holds to the same rule, verifying the password against a decoy when there is no account. |
POST /api/auth/reset-password | Set a new password using a token from that email. Body: { "token", "new_password" }. Single use, expires in an hour, and does not sign you in — you still log in normally, second factor included. Every existing session for the account ends. |
Account recovery
A user who loses their authenticator, or forgets their password, can be helped back in without anyone touching the database.
Who may do this. A platform operator, for any account. An admin or owner of an organisation, for members of that organisation they out-rank — so an admin cannot reset an owner. Nobody but an operator may reset an operator's credentials, even inside an organisation the operator belongs to. And an account that also belongs to another organisation is reset only by an operator (403 otherwise): the reset changes the one login every one of those organisations relies on, and authority in yours is not authority over theirs.
What an administrator learns: nothing. The password reset link is emailed to the account and is never returned by the API. Accounts are global while organisations are not, so a member of yours may belong to others — if you could read their reset link you could sign in as them and reach those other organisations too. Triggering the mail is the whole of the capability.
Clearing someone's authenticator is safe to hold for the same reason: it creates no credential. The account still needs its password, and enrollment is forced again at the next sign-in. The lost device stops working, which is the point.
| Method & path | Description |
|---|---|
POST /api/users/{id}/reset-mfa | Clear a user's enrolled authenticator so they can enroll a new one. Their existing sessions end too: a lost or stolen device is the usual reason, and a session opened with it is no less suspect. |
POST /api/users/{id}/reset-password | Email that user a reset link. Returns email_sent and, if it failed, email_error — never the link itself. |
POST /api/users/{id}/require-password-change | Require a new password before that account may do anything else. Body: { "required": true|false }. |
require-password-change lets the account sign in and then refuses it every endpoint except /auth/change-password and /auth/me until it complies. Enforced server-side, so an API client cannot carry on with a token it already holds, and read from the account on every request — setting it takes effect immediately rather than at the user’s next login, and so does clearing it. Completing either route to a new password clears it./auth/me, /auth/mfa/setup and /auth/mfa/activate with 403 mfa_enrollment_required until it has — in particular it cannot create an API key, which never asks for a second factor and would make enrolling optional. GET /auth/me reports mfa_enrollment_required so a client can route to enrollment rather than parse the refusal. A session issued through single sign-on is not asked: the organisation’s identity provider performed the authentication, including whatever second factor its policy requires. The forced password change above is checked first.If mail is down, Threatera’s operators can issue the link out of band. Whoever holds a reset link can use it, so that path is deliberately slower than a button and the link goes to the user directly — never into a ticket.
Two-factor authentication
Enrolling an authenticator app is a two-step handshake, so a lost secret can't lock an account out halfway: setup mints the secret but leaves MFA off until you prove you can generate a valid code.
| Method & path | Description |
|---|---|
POST /api/auth/mfa/setup | Begin enrollment. Returns { "secret", "otpauth_uri", "qr_svg" } — the QR is a ready-to-render SVG, so a client needs no QR library. 400 if MFA is already enabled. |
POST /api/auth/mfa/activate | Confirm enrollment with a current code. Body: { "otp" }. Turns MFA on and returns a fresh token. 400 for a wrong code, or if setup hasn't been called. The code is spent: it cannot then be used to sign in. |
Once enabled, a login without a valid otp returns 200 with { "mfa_required": true } and no token — a signal to prompt, not an error.
API keys
Create personal API keys for scripting. The plaintext key is shown once on creation — store it securely.
| Method & path | Description |
|---|---|
POST /api/api-keys | Create a key. Body: { "name", "expires_in_days", "scope" }, the lifetime 1–365 days (default 365). scope is full (default: acts as you) or collector: a send-only key for threatera watch, named as the collector it is, which can ask files/held, upload a file or a message and check in under that name and do nothing else — every other call is 403 collector_key_send_only. Returns the plaintext key once. Only from a signed-in session: an API key creating a key gets 403. |
GET /api/api-keys | List your keys (prefixes only, no plaintext). |
DELETE /api/api-keys/{id} | Revoke a key. |
GET /api/tenants/current/api-keys | Admins and owners. Every key in the organisation, whoever issued it, with the account that created each — prefixes only. |
DELETE /api/tenants/current/api-keys/{id} | Admins and owners. Revoke any key in the organisation. 404 if unknown or already revoked. |
expires_in_days defaults to 365 and cannot exceed it, and null — which once meant “never” — is refused with 422, the way enterprise platforms cap personal tokens. Keys made before that rule were given an expiry a year after they were created. The key list counts down a live key’s last month, so a lapse is seen before it happens. A key cannot create a key (403): otherwise one that leaked could be traded for a fresh one that outlived both its expiry and its revocation. Revoking one is never refused, whatever holds it. A key cannot be created for a service principal: 403, because a key is personal and there would be no person to attribute its actions to.Tenants
A tenant is a customer organisation. Analysis data belongs to exactly one; users reach it through a membership, which carries a role in that tenant (owner, admin, analyst, read-only).
Requests act inside one tenant. Send its TID in the X-Tenant header — optional when you belong to exactly one, required when you belong to several (otherwise 400, because guessing would mean acting in the wrong organisation's data). Asking for a tenant you are not a member of returns 403, and so does asking for one that does not exist: distinguishing the two would let anyone enumerate the customer list.
X-Tenant; a key cannot, because it skips the second factor and lives up to a year, so it should reach no further than where it was made. That holds for the /api/tenants/{id}/… routes as well: a key naming another organisation gets 403 even where you are its admin. To automate several organisations, create a key in each.t_9f4c2a71b8e03d56, from GET /api/me/tenants. It is random, so it names no customer, reveals no ordering and implies no count — safe in a header, a screenshot or a support ticket. It is not a credential: reaching an organisation still requires a membership, so a TID on its own grants nothing. Organisations also carry an internal slug, derived from their name; it is visible only to platform operators, and it is still accepted in X-Tenant so that integrations written before TIDs existed keep working.| Method & path | Description |
|---|---|
GET /api/me/tenants | Tenants you may act in, with your role in each. Drives the tenant switcher. Suspended tenants are omitted. |
GET /api/tenants/current | The tenant this request is acting in, resolved from X-Tenant or your single membership. |
POST /api/tenants/{id}/invites | Invite someone into this tenant — the only way anyone joins one. Body: { "email", "role" }. Somebody new creates their account by accepting (POST /api/auth/register); somebody who already has an account accepts while signed in (POST /api/auth/accept-invite). The answer is the same either way, so it says nothing about who holds an account on the installation. Requires admin in the tenant (or a platform operator), and you cannot invite above your own role. Returns the link whether or not the email was sent. 409 only if they are already a member here. |
GET /api/tenants/{id}/members | Who can reach this tenant. Readable by any member, not only admins — this list is how a customer verifies no unexpected account has access. Platform operators may read it too: they can already grant and revoke membership, so withholding the read would leave them able to add someone and unable to check the result. Each entry carries is_operator, true for a Threatera operator's own account, so every member can tell the vendor from a colleague. |
POST /api/tenants/{id}/members | Platform operators adding themselves — support access — and nothing else. Body: { "username", "role" }, where username is your own. It appears in the member list and the audit log, so the customer sees it. Anybody else is 403, before anything is looked up: an existing account joins by accepting an invitation, because membership is what several admin powers read as authority over the account, and it is never granted to somebody who did not ask for it. |
DELETE /api/tenants/{id}/members/{user_id} | Revoke access. 403 unless you are an admin of that organisation — asked first, so a caller who is not cannot learn whether the organisation exists or who belongs to it; then 404 if they are not a member; 403 if they out-rank you (an admin cannot remove an owner); 409 if they are the only owner — give someone else that role first, or the organisation would be left unable to administer itself. A platform operator's membership is removed like any other: ending the vendor's access is the customer's to do. |
GET /api/tenants operator | Every tenant. Platform operators only — this is the customer list. Each carries its plan (trial, customer, or null for one made before plans) and, for a trial, trial_ends_at. |
POST /api/tenants operator | Create a tenant. Body: { "slug", "name" }. 409 if the slug is taken. |
POST /api/tenants/{id}/trial/extend operator | Give a trial more days. Body: { "days" }, 1–90, counted from its end date, or from today if it has already ended. Audited. 409 if the organisation is not on a trial. |
POST /api/tenants/{id}/trial/convert operator | Make a trial a customer: plan becomes customer, the end date goes, and the quotas become what the body says — { "quota_storage_mb", "quota_uploads_per_day" }, each null (or left out) for no limit, never the trial's by default. Audited. The demo data stays until the organisation's admin removes it (DELETE /api/demo). Optional price_plan_id: the price plan it is charged on from now. 409 if it is not on a trial. |
PATCH /api/tenants/{id} | Body: { "name", "alert_email", "status", "quota_storage_mb", "quota_uploads_per_day", "sso_domains" }, all optional. An owner may set name and alert_email (see the watchlist digest; send null to clear it, omit it to leave it alone) for their own tenant; status and both quotas are operator-only, so a customer cannot lift their own limits. So is sso_domains — the email domains the organisation has shown it owns, and so the only ones its identity provider is routed for (see single sign-on). It replaces the stored list; public mail domains are refused, and 409 names any domain already verified for another organisation. status is one of active, suspended (a billing lapse, expected to be reversed) or deleted (the organisation has left). Only active grants access; neither of the others destroys anything, and both are reversible by setting it back. Erasure is a separate, manual operation. |
GET /api/tenants/{id}/key-provider | Whether this organisation's samples are encrypted under a key you hold. Readable by an admin of the organisation as well as by a platform operator — you are entitled to check your own answer. Returns { "configured", "provider", "config" }; never the credential, and never the wrapped key. |
PUT /api/tenants/{id}/key-provider operator | Point an organisation's key at a KMS the customer runs. Body: { "provider", "config", "secret" } — currently provider: "vault" with config: { "address", "key", "mount", "namespace" } for a HashiCorp Vault transit engine. Verified against the provider before it is stored, so a wrong address fails here rather than on an analyst's first unreadable file. 409 if customer-held keys are not enabled on the installation, if the organisation already uses a provider, or if it already holds samples — enabling a provider protects everything stored from that point and nothing before it, so an existing corpus needs accept_existing_corpus_stays_readable: true to confirm. |
POST /api/tenants/{id}/key-provider/check | Is the customer's KMS answering right now? Reports rather than fails: { "reachable", "detail" }, with the reason in plain words. This is the question an unreadable file turns into, and it is answerable without reading a worker's logs. Readable by an organisation admin or a platform operator. |
DELETE /api/tenants/{id}/key-provider operator | Hand the key back to the platform's own master key. This is a disclosure: afterwards the operator can read every sample the organisation holds. It requires the provider to still be reachable — the key must be unwrapped once in order to be re-wrapped — and it is recorded in the audit log saying exactly that. |
Admin admin
Member management, invites and the audit log — restricted to admins (403 otherwise). Admin means admin of an organisation: the role comes from your membership (owner or admin), and everything here is scoped to the organisation the request is acting in. Platform operators are admins everywhere.
| Method & path | Description |
|---|---|
POST /api/invites | Deprecated — use POST /api/tenants/{id}/invites. This route predates organisations and cannot name one, so it always invites into default; on an installation with more than one that is rarely what was meant. Body: { "email", "role" }. |
GET /api/invites | Pending invites for this organisation, each with its id (never the token). |
DELETE /api/invites/{id} | Revoke a pending invite — the emailed link stops working immediately. 404 if it was already accepted: the account exists, so disable the user instead. |
GET /api/users | The members of this organisation, with their role in it. ?scope=all returns every account on the installation instead and is operator only. |
PATCH /api/users/{id} | Change a member's role here, switch them off here, or enable/disable their account. Body: { "role"?, "access"?, "active"? }, role being one of owner, admin, analyst, read-only. 404 if they are not a member of this organisation — the same answer as a user id that does not exist, so this cannot be used to enumerate accounts. 403 if they out-rank you or if you try to grant a role above your own.
|
DELETE /api/users/{id} | Remove a member from this organisation (you cannot remove yourself). The account survives, because the same person may work for another customer; it is deleted only when this was its last organisation, and its API keys go with it. 409 if they are the only owner. |
GET /api/audit | A page of audit events, newest first (limit, offset). sort takes field:asc or field:desc over created_at, username, action or target — ordering by user or by action is most of the reason anybody opens this. q is a case-insensitive substring matched against the user, the action and the target together, because the thing you are asking about is as often a hash or a filename as it is a person; since and until (YYYY-MM-DD, whole days in UTC, inclusive) narrow it by date; total counts what matched rather than the whole log, so the pager describes the result and not the store behind it. |
GET /api/audit/export | Every event that matches, oldest first, as a file: format=csv (default) for a spreadsheet or format=jsonl — one JSON object per line — for a SIEM or an archive. Takes the list's q, since and until, so it exports exactly what the list shows. Columns at, user, action, target, detail, prev_hash, row_hash; in an unfiltered export each row's prev_hash is the previous row's row_hash, so a row taken out from between two others shows without the key. No event id: they are numbered across every organisation on the installation. In the CSV a value beginning with =, +, - or @ is prefixed with ' so a spreadsheet does not run it as a formula; JSON Lines carries every value exactly as recorded. X-Audit-Events is the count and X-Audit-Chain-Head the newest event's hash. 400 when more than 100,000 events match — narrow it by date rather than receive a file that stops short. Admin only, and the export is itself recorded before the log is read, so an unfiltered export ends with its own event.
request curl "https://app.threatera.eu/api/audit/export?format=jsonl&since=2026-10-01" \ -H "x-api-key: $THREATERA_KEY" -o audit-october.jsonl |
GET /api/audit/verify | Has this organisation's log been edited since it was written? Each event carries a keyed hash over its own contents and the previous event's, so an edited row, a removed one or two swapped stop reproducing. broken names the first event where that happens — its position in your organisation's log (oldest is 1), its time (at) and its row_hash, never an event id, which is numbered across every organisation on the installation — and reason says which it looks like. Three counts that must not be read as one: checked (covered), unchained (written before a key existed — never backfilled, because hashing them now would certify a history that could already have been edited) and holes (an unchained event after a chained one; nothing is proven across it). Write head down somewhere this platform cannot reach — a chain cannot detect the newest events being deleted, since what remains verifies perfectly, and two readings where head has not moved but events has fallen is that deletion. |
System health operator
Per-dependency status and resource usage. Probes Postgres, Elasticsearch, Redis, MinIO, ClamAV and the detonator concurrently, so the response takes as long as the slowest single probe rather than their sum.
Platform operators only. Nothing here is one organisation's data, but all of it is the installation's — which services exist, which are failing and with what error — which makes it an inventory of the platform to anyone renting it rather than running it.
{
"status": "degraded",
"degraded": ["clamav"],
"services": [
{"service":"postgres","status":"up", "latency_ms":2.1, "version":"16.4"},
{"service":"clamav", "status":"down","latency_ms":5002.0, "error":"probe timed out after 5s"}
]
}status is ok only when every dependency is up, otherwise degraded with the failing ones listed. A dependency that is down is reported, never raised — the whole point is to see which one broke, so a single failure can't take the response down with it.
Each entry always carries service, status and latency_ms. error appears only on failure, and healthy probes add their own detail fields (versions, signature counts, disk usage), so treat the extra keys as per-service rather than fixed.
GET /health instead.degraded can also name something that is not a dependency: job:retention when a scheduled job has stopped running, or unconsumed:analysis when a queue has no worker listening. Every service can be up while the work has quietly stopped, and those are the two ways it happens.Operator only. Whether the scheduled work actually ran, and whether anyone is consuming the task queues — a different question from the one above, and the one that has twice been answered wrongly by a page full of green.
| Field | What it is |
|---|---|
jobs | Every scheduled job with the cadence it is supposed to keep, its last start, last finish and last success, and a state: ok, overdue, failing, abandoned (started, never ended — a pod that went away) or unknown. |
workers | Which queues have a live consumer. A queue in unconsumed_queues is one whose work will never be done, reported whether or not anything is waiting in it. |
queue_depth | Backlog per queue. |
signals | What the runs, the meter and the polls say, across the installation: per kind (analysis, detonation, urlscan) the runs completed and failed in the last hour, those stuck running and those waiting to start for over two hours; sandbox runs and URL scans started_today against metered_today (UTC); and reporting mailboxes and EDR sources enabled and failing. Numbers only — no organisation. ok: false when they could not be read, never zeros. |
problems | The signals that need somebody, each as kind, subject and detail: runs failing, runs stuck, runs waiting, metering flat, polls failing, backlog. Empty when healthy. |
unknown, never ok. It has either never run or not run since this was added, and both are worth finding out. Defaulting an absence to healthy is exactly how a feature ships broken and stays that way — which is what happened to event delivery, discarded on arrival from the day it shipped while the API reported every event as queued.For the operator's Prometheus. The same signals, queue depth, consumers and silent jobs as /api/system/machinery, in Prometheus text format: threatera_signals_ok, threatera_runs{kind,outcome}, threatera_runs_stuck{kind,state}, threatera_started_today{metric}, threatera_metered_today{metric}, threatera_polls_enabled{source}, threatera_polls_failing{source}, threatera_queue_depth{queue}, threatera_queue_consumers{queue}, threatera_job_silent{job}.
Bearer token only: Authorization: Bearer the installation's METRICS_TOKEN, and 404 while none is configured, which is the default. Not a session or an API key — Prometheus signs in as nobody, and the route is served on the product's own hostname.
/openapi.json and Swagger UI at /docs, where Authorize lets you send your API key or JWT with the requests you try.
Comments
Attributed, free-text notes on a file or an indicator — the analyst context that doesn't fit in a tag. Any authenticated user can comment; the author is recorded from the credential.
The comment thread on one artefact, newest first. Optional
limit(1–500, default 100).fileoriocfile, a SHA-256. Forioc, an IP or domain.Evil-C2.COMandevil-c2.comresolve to the same thread rather than splitting the discussion in two.Comments are addressed by value, not by foreign key — you can annotate something that hasn't been ingested yet, and the thread survives re-ingestion.
400if the target type or value is malformed.Add a comment. Body:
{ "body": "…" }— non-empty after trimming, at most 4000 characters (422otherwise). Returns201with the stored comment, and404unless your organisation holds the file or indicator — a comment on something that is not here has no page to be read on.{ "id": 7, "target_type": "ioc", "target_value": "evil-c2.com", "author": "alice", "body": "Seen in the Acme phishing wave, 2026-07-19.", "created_at": "2026-07-28T09:14:52Z" }Delete a comment. Allowed for its author or an admin;
403for anyone else,404if it doesn't exist. Returns204./api/commentslimit1–100, default 20./api/comments/counts{ "file:<sha256>": 3, "ioc:evil-c2.com": 1 }. Lets a list view show badges without one request per row.There is no voting or reputation scoring — that needs a trust model this deployment doesn't have.