Quickstart
Score your first response with the Cipher API in a few minutes.
This walks through one request end to end: get a key, send a response, read the verdict. For the full parameter reference, see Cipher SDK and API.
1. Create an API key
Go to Settings, then Connectors and create a key. Keys look like
cipher_sk_... and carry a tier limit, which caps the checks a request can ask
for. See API keys for scopes and rotation.
Keep the key server-side. Every tier is scored on Surbee's servers, so there is never a reason to ship one to a browser.
export CIPHER_API_KEY="cipher_sk_..."2. Send a response
Post the response you collected to /api/cipher/validate, along with the tier
you want. Tiers 1 and 2 are rule-based and return in milliseconds at no cost.
import { Cipher } from '@surbee/cipher';
const cipher = new Cipher({ apiKey: process.env.CIPHER_API_KEY!, tier: 2 });
const result = await cipher.validate({
responses: [{ question: 'Would you recommend us?', answer: 'Yes' }],
});
console.log(result.score, result.recommendation);import os, requests
result = requests.post(
"https://surbee.dev/api/cipher/validate",
headers={"Authorization": f"Bearer {os.environ['CIPHER_API_KEY']}"},
json={
"tier": 2,
"input": {
"responses": [{"question": "Would you recommend us?", "answer": "Yes"}]
},
},
).json()
print(result["score"], result["recommendation"])curl https://surbee.dev/api/cipher/validate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $CIPHER_API_KEY" \
-d '{
"tier": 2,
"input": {
"responses": [
{ "question": "Would you recommend us?", "answer": "Yes" }
]
}
}'3. Read the verdict
{
"score": 0.91,
"passed": true,
"recommendation": "keep",
"flags": []
}score runs from 0 to 1, where higher is better. recommendation is keep,
review, or discard, derived from your thresholds. Act on the
recommendation rather than the raw score, so changing a threshold does not mean
changing your code.
Send behavioral signals for a real score
A response with no timing or device signals can only be judged on its text.
Pass behavioralMetrics and deviceInfo alongside responses to unlock the
timing, device, and automation checks. See Cipher checks.