Orbis Shield API
The Orbis Shield API lets you call ROUNDBOX threat‑intelligence and message‑inspection directly from your own systems — a custom SMS/WhatsApp gateway, a firewall or SIEM enrichment step, a reputation‑lookup service, or any backend that needs a fast verdict.
Base URL
https://shield.orbis.roundbox.dev/api/v1
All requests use TLS. Responses are JSON.
What you can call
| Module | Endpoint | Purpose |
|---|---|---|
| Identity | GET /whoami | Confirm the tenant + scopes behind your API key |
| URL Filter | GET /urlsearch | Reputation/category for a URL or domain |
| IP Reputation | GET /ipsearch | Reputation for an IP or ASN |
| DNS Reputation | GET /dnssearch | Reputation for a domain |
| Darkweb Lookup | GET /darkweb | Credential-breach exposure for a verified domain (Safe / Breached / unavailable) |
| Antispam / Antiphishing | POST /antispam | Full L1–L4 inspection of a message |
| File scan | POST /files, /files/dynamic, /files/hash, /files/hash/lookup | Submit a file (or hash) for static + dynamic malware analysis |
| File job status | GET /files/{jobId}, /files/{jobId}/events | Poll a scan job and stream its events |
| Detections | GET /detections, /detections/{sha256}, /detections/{sha256}/runs | Query stored detections + sandbox runs |
| Scoring rubric | GET /scoring-rubric | The verdict/score rubric Shield applies |
Each endpoint requires an API key scoped to that module (see Authentication).
How it fits together
- Create a tenant API key in the Orbis Shield portal (Developer → API keys) and grant it the module scopes you need.
- Call the endpoints below with your
X-Tenant-IDandX-API-Key. - Optionally, register webhooks so Shield calls you when an inspection is flagged.
Rate limits & quota
Calls count against your tenant's monthly quota. When the quota is exhausted the API
returns 429 Too Many Requests. Your current usage, cost per message, and remaining
quota are visible in the portal under Billing.
Errors
Standard HTTP status codes:
| Status | Meaning |
|---|---|
200 | Success |
400 | Bad request (missing/invalid parameter) |
401 | Missing or invalid X-Tenant-ID / X-API-Key |
403 | The key lacks the scope for this module |
429 | Monthly quota exceeded |
Error bodies are JSON: { "statusCode": 403, "message": "API key is missing the required scope: darkweb" }.