API Reference

Switch primitives via the task field: use choice for multiple-choice, score for ordered scoring, and noul for open judgment without preset options. All three share one endpoint and the same response shape.

Three common client patterns. Point ENDPOINT at the public endpoint or your private intranet address — the request and response shapes are identical.

bashcurl -X POST https://api.unfork.ai/v1/systemone \
  -H "Content-Type: application/json" \
  -d '{
    "task": "choice",
    "text": "Refund request is 3 days overdue, but credit history is excellent. Approve automatically?",
    "candidates": ["approve", "reject", "escalate_to_human"]
  }'

pythonimport requests

ENDPOINT = "https://api.unfork.ai/v1/systemone"

def decide(text, candidates, threshold=0.85):
    res = requests.post(ENDPOINT, json={
        "task": "choice",
        "text": text,
        "candidates": candidates,
    }, timeout=12).json()

    decision = res["decision"]
    confidence = res["calibrated_confidence"]
    probs = res.get("probabilities", [])

    # Low confidence → escalate to human; high confidence → execute directly
    if confidence < threshold:
        return {"route": "human_review", "reason": "low_calibrated_conf",
                "confidence": confidence, "probs": probs}
    return {"route": "execute", "decision": decision, "confidence": confidence}

print(decide("Large withdrawal request from an unusual location",
             ["allow", "challenge_otp", "block_and_alert"]))

javascriptconst ENDPOINT =
  "https://api.unfork.ai/v1/systemone";

async function decide(text, candidates) {
  const res = await fetch(ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ task: "choice", text, candidates }),
  });
  if (!res.ok) throw new Error(`decide failed: ${res.status}`);
  const data = await res.json();
  return { decision: data.decision, confidence: data.calibrated_confidence };
}

// Batch concurrency: each text is decided independently; results can go straight into the audit table
const texts = ["Ticket A content", "Ticket B content", "Ticket C content"];
const results = await Promise.all(
  texts.map((t) => decide(t, ["route_billing", "route_tech", "escalate"]))
);
console.log(results);

Set a 12-second timeout and a retry cap per request; if the endpoint is unavailable, degrade by business criticality (e.g. route to a human or use a cached decision).

Standard HTTP status codes are used; on failure a JSON error object is returned with an error field describing the cause, making unified client handling straightforward.

json{
  "error": "invalid_candidates",
  "message": "choice primitive requires at least 2 candidates",
  "status": 400
}

Confidence Routing Guidance

Use calibrated_confidence for single- or dual-threshold routing: execute at high confidence, escalate at low confidence to System 2 or a human, and sample-review the middle band.

Calibrate thresholds against business risk and human cost; public benchmarks show good calibration, so 0.85 is a sensible general starting point.