API Reference

Base URL

https://api.securilayer.dev

All endpoints accept and return JSON. Authentication via Authorization: Bearer <token> header unless marked as public.

Authentication

Telegram WebApp Auth

POST /v1/auth/telegram-webapp Public

Authenticate using Telegram WebApp initData. Returns a JWT access token.

{
  "init_data": "query_id=AAH...&user=%7B...%7D&auth_date=...&hash=..."
}

Response:

{
  "access_token": "eyJhbG...",
  "user_id": 42,
  "org_id": 1,
  "username": "john"
}

Telegram Login Widget

POST /v1/auth/telegram Public

Authenticate via Telegram Login Widget callback data (id, first_name, hash, etc.).

Current User

GET /v1/auth/me Auth

Returns the authenticated user's profile, org, plan status.

Decision Checks

Check URL

POST /v1/decision/url Auth

{
  "url": "https://suspicious-site.example.com",
  "platform": "telegram"
}

Response — a full Decision Contract summary:

{
  "decision_id": "dc_a1b2c3d4-...",
  "verdict": "block",
  "confidence": 0.92,
  "confidence_label": "HIGH",
  "reasons": [
    "Domain registered <7 days ago",
    "Brand impersonation detected: paypal",
    "Suspicious TLD: .xyz"
  ],
  "homograph_suspected": false,
  "object_type": "url",
  "object_ref": "sha256:..."
}

Check Text

POST /v1/decision/text Auth

Scan a text message for social engineering patterns and embedded URLs.

Cache Lookup

GET /v1/decision/cache/lookup?url_hash=sha256:... Auth

Fast lookup by URL hash — returns cached verdict if available.

Check Phone

POST /v1/check/phone Auth

{
  "phone": "+1234567890",
  "platform": "telegram"
}

Returns fraud score, carrier info, and risk indicators for the phone number.

Check File

POST /v1/check/file Auth

Upload a file (multipart/form-data) for malware hash lookup and content analysis. Max 10MB.

Check Media

POST /v1/check/media Auth

Analyze media files (images, documents) for embedded threats, steganography, and malicious metadata.

Decision Contracts

List Contracts

GET /v1/decisions?limit=20&offset=0 Auth

Returns Decision Contracts for the current organization, newest first.

Get Contract

GET /v1/decisions/{decision_id} Auth

Full Decision Contract with all evidence references, policy version, confidence, and actions applied.

Create Contract

POST /v1/decisions Auth

Create a Decision Contract manually (for API integrations).

SDR / Referrals

Method	Endpoint	Description
GET	/v1/sdr/dashboard	Full SDR dashboard: conversions, revshare, recruited SDRs, payouts
GET	/v1/sdr/referrals	List all referral links
POST	/v1/sdr/referrals	Create a referral link
DEL	/v1/sdr/referrals/{id}	Deactivate a referral link
GET	/v1/sdr/wallet	Current payout wallet
PUT	/v1/sdr/wallet	Set/change wallet address (7-day cooldown)
POST	/v1/sdr/wallet/confirm	Confirm wallet — "Are you sure?"
GET	/v1/sdr/conversions	List conversions
GET	/v1/sdr/payouts	List payouts

Payments

Crypto (USDT via NOWPayments)

POST /v1/payments/crypto/link Auth

Creates a NOWPayments hosted invoice. Returns invoice_url for redirect. Supports USDT, BTC, TON, BNB.

Crypto Invoice Status

GET /v1/payments/crypto/invoice/{provider_payment_id} Auth

Returns current invoice state for WebApp polling and checkout reconciliation.

Crypto Webhook (IPN)

POST /v1/payments/crypto/webhook

NOWPayments IPN callback. Verified via HMAC-SHA512 (x-nowpayments-sig header).

Admin & Approvals

Method	Endpoint	Description
GET	/v1/approvals	List pending approval requests
POST	/v1/approvals/{id}/approve	Approve (4-eyes)
POST	/v1/approvals/{id}/reject	Reject with reason
GET	/v1/admin/analytics	Org-level analytics (scans, blocks, FP rates)
GET	/v1/admin/sdr/summary	Admin SDR overview
POST	/v1/admin/sdr/payouts/{id}/action	Approve/freeze/cancel/mark_paid payout
GET	/v1/export/siem	SIEM export (JSON/Syslog)

Ban Management

Method	Endpoint	Description
GET	/v1/bans	List all bans for the organization (paginated)
POST	/v1/bans	Create a ban (user ID, phone, domain, or hash)
DEL	/v1/bans/{ban_id}	Remove a ban
GET	/v1/bans/export	Export ban list as CSV
POST	/v1/bans/import	Import ban list from CSV

Create ban example:

{
  "type": "domain",
  "value": "phishing-site.example.com",
  "reason": "Confirmed phishing domain",
  "expires_at": null
}

Incidents

Method	Endpoint	Description
GET	/v1/incidents	List security incidents (filterable by status, platform, severity)
PATCH	/v1/incidents/{decision_id}/resolve	Resolve an incident with resolution notes

Integration Management

Telegram

Method	Endpoint	Description
POST	/v1/telegram/link-group	Link a Telegram group/channel to your organization
GET	/v1/telegram/linked-groups	List all linked Telegram groups
PATCH	/v1/telegram/groups/{chat_id}/settings	Update group scanning settings (mode, filters, actions)
GET	/v1/telegram/linked-groups/{chat_id}/diagnostics	Group diagnostics (bot permissions, scan stats, last activity)
DEL	/v1/telegram/link-group/{chat_id}	Unlink a Telegram group

Discord

Method	Endpoint	Description
POST	/v1/discord/servers	Register a Discord server
GET	/v1/discord/servers	List linked Discord servers
PATCH	/v1/discord/servers/{guild_id}/settings	Update server scanning settings
GET	/v1/discord/diagnostics/{guild_id}	Server diagnostics and health check

Slack

Method	Endpoint	Description
GET	/v1/slack/workspaces	List connected Slack workspaces
DEL	/v1/slack/workspaces/{team_id}	Disconnect a Slack workspace
PATCH	/v1/slack/workspaces/{team_id}/settings	Update workspace scanning settings

Webhook Configuration

Method	Endpoint	Description
POST	/v1/webhooks	Create a webhook endpoint
GET	/v1/webhooks	List configured webhooks
GET	/v1/webhooks/{webhook_id}	Get webhook details
DEL	/v1/webhooks/{webhook_id}	Delete a webhook
POST	/v1/webhooks/{webhook_id}/rotate	Rotate webhook signing secret
POST	/v1/webhooks/{webhook_id}/test-delivery	Send a test webhook delivery
GET	/v1/webhooks/deliveries	View delivery logs

Webhook Events

SecuriLayer sends events to your configured webhook URL with HMAC-SHA256 signature.

Headers

X-SecuriLayer-Signature: sha256=<hmac_hex>
X-SecuriLayer-Timestamp: 1708300000
Content-Type: application/json

Verification

import hmac, hashlib
expected = hmac.new(
    secret.encode(), timestamp + body, hashlib.sha256
).hexdigest()
assert hmac.compare_digest(expected, signature)

Error Handling

All errors return JSON with detail field:

{
  "detail": "Rate limit exceeded. Try again in 42 seconds."
}

Code	Meaning
400	Bad request / validation error
401	Authentication required or token expired
403	Insufficient permissions / KYC required
404	Resource not found
429	Rate limit or billing limit exceeded
502	Upstream service error (Telegram API, etc.)
503	Feature not configured

Rate Limits

Plan	URL+Text/day	File/day	Evidence TTL
Free	20	5	0–1 day
Pro	200	25	7 days
Teams	2,000	250	30 days
Company	10,000	1,000	180 days

When limits are exceeded, the API returns 429 with a detail explaining the limit and next reset time.

Code Examples

cURL — Check URL

curl -X POST https://api.securilayer.dev/v1/decision/url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "platform": "api"}'

Python — Check URL

import requests

resp = requests.post(
    "https://api.securilayer.dev/v1/decision/url",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": "https://example.com", "platform": "api"},
)
data = resp.json()
print(data["verdict"], data["confidence"])

JavaScript — Check URL

const resp = await fetch("https://api.securilayer.dev/v1/decision/url", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com", platform: "api" }),
});
const data = await resp.json();
console.log(data.verdict, data.confidence);

Python — Verify Webhook Signature

import hmac, hashlib

def verify_webhook(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(), (timestamp + body.decode()).encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)