API Reference · v1
One endpoint. Several verdicts.
Every Cyphic product is reachable via a single POST /v1/decide. Pick the product, ship the payload, deduct the tokens.
Sentinel
Real-time fraud and payment risk verdict.
curl -X POST https://api.cyphic.ai/v1/decide \
-H "Authorization: Bearer cyp_live_…" \
-H "Content-Type: application/json" \
-d '{"product":"sentinel","payload":{"amount":4800,"currency":"USD","card_bin":"424242","ip":"51.x.x.x","email":"a@b.io","device_id":"dvc_91"}}'{
"product": "sentinel",
"payload": {
"amount": 4800,
"currency": "USD",
"card_bin": "424242",
"ip": "51.x.x.x",
"email": "a@b.io",
"device_id": "dvc_91"
}
}{
"risk_score": 92,
"action": "block",
"reasons": [
"high_velocity",
"bin_blacklist"
],
"decision_id": "dec_01HXY"
}Token cost breakdown
Authentication
Bearer keys. Scoped. Rotatable.
Every request to /v1/decide carries a project key in the Authorization header. Keys are environment-scoped (cyp_live_ / cyp_test_), can be rotated at any time, and are tied to per-product permissions you control from the console.
# Header Authorization: Bearer cyp_live_xxx Content-Type: application/json Idempotency-Key: <uuid> # optional, dedupes retries X-Cyphic-Project: prj_42 # optional, multi-project accounts
Errors
Predictable HTTP codes. Actionable bodies.
Schema validation failed. Check the field listed in `error.path`.
Missing or revoked key. Rotate from the console and retry.
Plan tokens depleted. Top up or upgrade — verdict is not billed.
Burst exceeded. Honour `Retry-After`. Defaults: 60 rps, 1k rpm.
We log and page on every 5xx. Retry with same Idempotency-Key.
Cold model. Safe to retry after 200ms.
External signal source slow. Fallback verdict returned in `meta.fallback`.
Partial verdict only. `confidence` will be marked `low`.
Rate limits
Default: 60 rps / 1,000 rpm per key. Headers X-RateLimit-Remaining and Retry-After are always returned. Enterprise plans lift limits on request.
Client SDKs
First-party libraries for Node/TypeScript, Python and Go are on the roadmap; until then, the REST API is fully usable from any HTTP client. Reference snippets for cURL, JS fetch and Python requests are above.
Webhooks
Subscribe to verdict events and case updates. Deliveries are signed (X-Cyphic-Signature: t=…,v1=…), retried with exponential backoff, and replayable from the console for 30 days.
Security & compliance
Built to the bar customers audit against.
Engineering practices
- TLS 1.2+ in transit, AES-256 at rest, per-tenant key isolation.
- Least-privilege IAM with short-lived tokens for internal services.
- Immutable, tamper-evident audit log on every decision (LedgerGuard-anchored).
- Region-pinned data residency for EU, UK and APAC workloads on request.
- Regular third-party penetration tests on the public API surface.
Certifications — underway
SOC 2 Type I and ISO/IEC 27001 readiness programs are in progress with an external auditor; GDPR and UK GDPR data-processing addenda are available today. We don't publish badges we haven't earned — request our current control mapping (NIST CSF, NIS2-aligned) and we'll share it under NDA.
Status updated quarterly.
Changelog
Shipping cadence — small, frequent, reversible.
- v1.0.4Idempotency-Key support on /v1/decide; webhook replay window extended to 30 days.
- v1.0.3VisualSafe added (image + video). Token cost: 10 per image, 15 per video.
- v1.0.2Regional pricing & currency localisation on the billing API.
- v1.0.1SocialGuard general availability. Bulk endpoint preview for Sentinel.
- v1.0.0Limited access version /v1/decide with Sentinel, HostGuard, TrustIQ, Assist, LedgerGuard.
Breaking changes are versioned at the URL prefix. Non-breaking additions ship behind feature flags. We commit to a 12-month deprecation window on any retired endpoint.