api reference · v1

POST /v1/predict

Updated May 12, 2026

Classify a single piece of text. Returns a calibrated softmax probability between 0 and 1 — higher means more likely to be spam.

Request

Authenticate with the X-API-Key header. The body is a single JSON object:

field	type	notes
text	string	1–20,000 characters. Truncated to 512 tokens server-side.

curl

curl -sX POST https://api.siftfy.io/v1/predict \
  -H "X-API-Key: $SIFTFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Win a free iPhone! Click here NOW"}'

python

import os
import requests

resp = requests.post(
    "https://api.siftfy.io/v1/predict",
    headers={"X-API-Key": os.environ["SIFTFY_KEY"]},
    json={"text": "Win a free iPhone! Click here NOW"},
    timeout=5,
)
print(resp.json()["spam_probability"])  # 0.987

javascript

const resp = await fetch("https://api.siftfy.io/v1/predict", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.SIFTFY_KEY,
  },
  body: JSON.stringify({ text: "Win a free iPhone!" }),
});
const { spam_probability } = await resp.json();

Response

json

{
  "spam_probability": 0.987,
  "likelihood": "high"
}

field	type	notes
spam_probability	number	Float in [0, 1]. We suggest a threshold of 0.85 for binary blocking.
likelihood	"low" \| "medium" \| "high"	Coarse bucket: `low` (<0.50, clean), `medium` (0.50–0.85, queue for review), `high` (≥0.85, safe to block).

Calibration

Scores are calibrated softmax probabilities, not thresholded labels — at 0.7, roughly 70% of inputs with that score are actually spam. Pick the threshold appropriate to your false-positive tolerance; the same model serves help-desk forms and marketplace listings off one knob.

Where to next

Errors → the four 4xx codes you'll see and what to do about each.
Rate limits → per-tier caps and the X-RateLimit response headers.
SDKs → the official Python client wraps this endpoint with retries.