HTTP API

export MANTIS=http://localhost:3000
export KEY=mantis_live_...   # `mantis login` output, or read from the bootstrap log

# Mint a key
curl -sX POST $MANTIS/api/keys \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"memo":"first mantis","destinations":[{"channel":"webhook","target":"https://webhook.site/<your-id>"}]}'
# → { "id":"...", "public_id":"...", "url":"http://localhost:3000/c/...", ... }

# Trigger it
curl -i $MANTIS/c/<public_id>
# → 200 OK with a 1×1 transparent GIF

# Inspect hits
curl -s $MANTIS/api/keys/<id>/hits -H "Authorization: Bearer $KEY" | jq

​

Endpoint reference

​

API key scope: full vs enroll

• full (default) — behaves as described throughout this page. Subject to the admin / non-admin visibility rules.
• enroll — create-only. An enroll key may call only POST /api/keys. Every other management route (list/read/update/delete keys — including the ones it created — plus /api/hits/recent, /api/api-keys, the audit log, and any session-reachable route) returns 403 forbidden, and an enroll key cannot log in to the dashboard. is_admin: true together with scope: "enroll" is rejected at validation.

• It can recover the trigger URL of any key whose external_id it guesses. A POST /api/keys that collides with an existing external_id returns that key’s trigger URL, public_id and expiry ("reused": true, HTTP 200) even when a different API key created it — the memo is null in that case and alert routing is never included; see Idempotent creation. This is what lets a re-imaged machine, or a rotated enroll key, find its canary again, and it is the one thing an extracted enroll key can do beyond creating keys. mantis device derives external_ids deterministically as mantis:device:<os>:<normalized-name>:<slug>, so an attacker who knows your naming convention can guess a machine’s ids and read back that machine’s canary URLs, which is exactly what lets an intruder route around the tripwires. Each cross-key claim is recorded in the audit log as key.claimed with cross_key: true — watch for a burst of them. (A full-scope key that did not create the key gets 409 instead and learns nothing.)
• It can supply destinations on creation, and Mantis fires the activation ping synchronously — so the key can make your instance POST to an attacker-chosen HTTP(S) endpoint (private, loopback and metadata addresses are rejected unless ALLOW_PRIVATE_WEBHOOKS=1) or, if SMTP_URL is set, send it mail.

​

Idempotent creation

• the key’s creator, or an admin — the key as they could read it anyway (full shape for full keys; the reduced shape below for enroll keys);
• an enrollment-scoped key that did not create it — the reduced shape: trigger URL, public_id, external_id, expiry and disabled, with memo set to null. No alert routing, no signing secrets. Audited as key.claimed with cross_key: true;
• any other full-scope key — 409 conflict with no key details, audited as key.claimed with denied: true. If you rotate the full-scope key that ran a pre-provisioning script, re-run it with an admin key.

​

Notification rows in hit listings

​

Response kinds for the trigger endpoint

​

Webhook payload

{
  "type": "mantis.hit",
  "key": { "id": "...", "public_id": "...", "memo": "...", "url": "..." },
  "hit": {
    "id": "...",
    "occurred_at": "2026-05-12T10:00:00.000Z",
    "ip": "203.0.113.5",
    "user_agent": "Mozilla/5.0 ...",
    "referer": null,
    "ua_browser": "Chrome",
    "ua_os": "macOS",
    "ua_device": "desktop",
    "bot_label": null,
    "is_duplicate": false,
    "headers": { "host": "...", "accept": "...", "x-mantis-source": "shell", "x-mantis-user": "alice", "x-mantis-ssh-client": "203.0.113.42 54321 22", "..." : "..." }
  }
}

"host_context": {
  "source": "shell",
  "user": "alice",
  "host": "alice-mbp",
  "ssh_client": "203.0.113.42 54321 22",
  "ssh_client_ip": "203.0.113.42",
  "ssh_connection": "203.0.113.42 54321 10.0.0.5 22",
  "tty": "/dev/pts/0",
  "sudo_cmd": null,
  "network_interface": null
}