Modules & Endpoints

All examples assume the base URL https://shield.orbis.roundbox.dev/api/v1 and the two auth headers from Authentication.

Threat-intelligence lookups

These return a fused verdict across ROUNDBOX threat-intelligence sources:

{
  "type": "domain",
  "value": "example.com",
  "disposition": "malicious",     // malicious | suspicious | clean | unknown
  "threatLevel": 82,               // 0–100
  "confidence": 90,                // 0–100
  "categories": ["phishing"],
  "malwareFamily": "...",          // when known
  "sources": ["abusech-urlhaus"],
  "firstSeen": "2026-06-01T00:00:00.000Z",
  "lastSeen": "2026-07-02T00:00:00.000Z",
  "found": true
}

URL Filter — GET /urlsearch · scope urlsearch

Query	Notes
value	The URL or domain (required)
type	url (default) or domain

curl "https://shield.orbis.roundbox.dev/api/v1/urlsearch?value=http://bad.example/login" \
  -H "X-Tenant-ID: $TENANT" -H "X-API-Key: $KEY"

IP Reputation — GET /ipsearch · scope ipsearch

Query	Notes
value	IP address or ASN (required)
type	ip (default) or asn

DNS Reputation — GET /dnssearch · scope dnssearch

Query	Notes
value	Domain (required)

Darkweb Lookup — GET /darkweb · scope darkweb

Dark-web lookup is domain-only — it checks whether credentials tied to your organization's domain have surfaced in a known breach. Unlike the other reputation lookups above, it requires a one-time domain ownership verification before it will return results for that domain.

1. Verify domain ownership (one-time, per domain)

1. In the portal, go to Developer → Domains → Add domain and enter the FQDN (e.g. acme.example).

2. Shield returns a DNS TXT ownership challenge. Publish it at your DNS provider:

   Record (TXT)	Value
   _orbis-shield-challenge.acme.example	orbis-shield-site-verification=<token>

3. Back in the portal, click Verify. Shield re-checks the TXT record; once it's found, the domain's status flips to Verified.

Verification is scoped per tenant — if two tenants both register the same domain, each verifies independently with its own token. A previously verified domain that later loses its TXT record can revert to unverified on a subsequent re-check.

2. Call the lookup

Query	Notes
value	The domain to check (required, FQDN — there is no type param)

curl "https://shield.orbis.roundbox.dev/api/v1/darkweb?value=acme.example" \
  -H "X-Tenant-ID: $TENANT" -H "X-API-Key: $KEY"

Calling /darkweb for a domain that isn't verified yet returns 403:

{ "statusCode": 403, "error": "domain-not-verified", "message": "Verify ownership of acme.example before running dark-web lookups. Add it under Domains and publish the DNS TXT challenge." }

Response:

{
  "domain": "acme.example",
  "status": "breached",
  "breachCount": 2,
  "latestBreach": "2024-03-11",
  "records": [
    {
      "email": "user@acme.example",
      "passwordMasked": "0ae6**********",
      "compromiseType": "password",
      "breachDate": "2024-03-11",
      "hashType": "bcrypt"
    }
  ],
  "checkedAt": "2026-07-22T18:04:11.000Z"
}

status is one of:

• safe — no known credential exposure found for the domain.
• breached — one or more compromised-credential records were found; each one is listed under records. Passwords are always masked (passwordMasked, e.g. 0ae6**********) — Shield never stores, returns, or re-derives the plaintext password.
• unavailable — the check could not complete. Treat this as "no result available," never as "safe" — a disabled provider or a failed lookup must not be read as "no exposure found."

The response never includes cost, price, or billing information — only the exposure verdict and (when breached) the masked records.

Antispam / Antiphishing — POST /antispam · scope antispam

Runs the full L1–L4 inspection pipeline on a message and returns a verdict.

Request body:

{
  "channel": "sms",              // email | sms | whatsapp
  "sender": "+15550100",
  "subject": "Optional subject",
  "body": "Your account is locked, verify at http://bad.example/login"
}

curl -X POST "https://shield.orbis.roundbox.dev/api/v1/antispam" \
  -H "X-Tenant-ID: $TENANT" -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"sms","sender":"+15550100","body":"verify at http://bad.example/login"}'

Response:

{
  "inspectionId": "…",
  "verdict": "phishing",          // clean | spam | phishing
  "score": 88,                     // 0–100 risk score
  "lang": "en",
  "urls": ["http://bad.example/login"],
  "layers": [ { "layer": "L1", "score": 10, "signals": ["…"] }, "…" ],
  "rationale": "Plain-language explanation (when the AI layer is available)"
}

Each POST /antispam counts as one inspection against your monthly quota and can trigger your webhooks.

Example: SMS gateway integration

Incoming SMS ─▶ your gateway ─▶ POST /api/v1/antispam ─▶ verdict
   └─ if verdict = phishing/spam: block or quarantine, and/or receive a webhook.