Decision API documentation
Two endpoints, one model. Send a state and a schema of typed questions, receive a probability for every allowed option. This page is the complete reference.
Two endpoints, one model
POST /api/v1/decisions is the systemone contract, the same shape jevapi.pro serves: a state plus typed questions, each carrying its own criteria. It needs an API key and it is the one to use in a pipeline.
POST /api/decide is the playground contract: the same state, but each question is a prompt with an options list. It works without a key and is counted per browser session, so it is what the interactive demo calls.
For a runnable free example, open /playground, load the support ticket and press Decide. The result shows every candidate probability, the actual model and provider, the requestId for that call, and the exact curl request to copy. Repeating it uses the same session allowance; it does not issue a refund. Browser timing includes the network and server and is separate from Cloudflare’s published benchmark, not an SLA.
Both run the same model and return the same probabilities. Pick one and stay with it: switching shape mid-project buys nothing.
Systemone request
curl -X POST https://clef-flash.com/api/v1/decisions \
-H 'content-type: application/json' \
-H 'authorization: Bearer cfl_0123456789abcdef0123456789abcdef' \
-d '{
"text": "Customer wrote: I was charged twice for the October invoice.",
"questions": [
{
"id": "intent",
"type": "choice",
"instructions": "What does the customer want?",
"criteria": {
"billing": "a charge, invoice or refund",
"technical": "something is broken or misbehaving",
"cancellation": "they want to stop paying"
}
},
{
"id": "urgency",
"type": "score",
"instructions": "How quickly does this need a human?",
"criteria": ["whenever", "this week", "today", "immediately"]
}
],
"threshold": 0.85
}'
Question types
A question declares what kind of answer it wants, and criteria is where that answer lives.
- choice —
criteriais an object of 2 to 12 labels, each mapped to one line of guidance for the model. The answer is the winning label plus the full distribution. - noul —
criteriais exactly{ "true": …, "false": … }. The answer isnoul, a single probability that the statement is true. There is no confidence field on a noul answer; comparenoulwith your own band. - score —
criteriais an array of 2 to 7 ordered levels, worst to best. The answer isscore, a continuous value between 0 and the last level index, plus the distribution over levels and alegendthat maps each index to its level. - The single-label body from older clients still works: send
instructionsandlabels(a list, or an object of label to guidance) instead ofquestions, and the answer arrives under the idcategory.
The body a jev client already sends
The systemone clients in the Jev family key questions by id instead of using an array, and they send the state as a JSON object. That body works here unchanged — the id comes from the key:
model may name jev, jev-latest, kev or kev-latest. Those are aliases for "the model behind this endpoint", answered by this deployment’s default model. They are names, not weights: kev here is not Jared Palmer’s Kev, it is whatever this deployment runs by default. To reach a specific model, name it — cloudflare/clef-flash, cloudflare/clef or jaredpalmer/kev-4b. The response always reports the model that actually answered, and any other name is refused rather than swapped.
jev-style body
{
"model": "jev-latest",
"state": { "page": { "h1": "Picking a drill bit", "opening": "Choose the bit by material." } },
"questions": {
"page_type": {
"type": "choice",
"instructions": "Which kind of page is page?",
"criteria": { "article_or_guide": "an editorial article or guide", "pricing": "plans or prices" }
}
}
}
Which model answers
Three vendors publish decision models under this same contract — a state, typed questions, calibrated probabilities. The request shape is identical; the weights, the price and the context window are not. A family name is not a model: jev is TypeSafe’s, kev is Jared Palmer’s, clef is Cloudflare’s.
This deployment serves exactly these four, and nothing else. Naming one of them is the only way to pin the answer to specific weights.
cloudflare/clef-flash(aliasclef-flash) — Cloudflare, 9B, 24,576-token context, up to 120,000 characters of state, text and images, $0.019 per million input tokens. The default.cloudflare/clef(aliasclef) — Cloudflare, 27B, 16,384-token context, up to 80,000 characters, text and images, $0.042 per million input tokens. Slower, more precise.cloudflare/clef-omni(aliasclef-omni) — Cloudflare, 65,529-token context, up to 200,000 characters, text and images, $0.15 per million input tokens. For states the smaller windows would cut short.jaredpalmer/kev-4b(aliaskev-4b) — Jared Palmer, 4B, 8,192-token context, up to 20,000 characters, text only, $0.042 per million input tokens.jev,jev-latest,kev,kev-latest— aliases, not models. They resolve to this deployment’s default model, and the response says which one that was.
How much of a state the model reads
A request body may be much larger than the model’s context window, and those two limits are not the same limit. Paid keys accept bodies up to 8 MB; a state is capped per model, below, and the cap is enforced here before anything is sent upstream.
Those caps are not arbitrary. Measured against the live endpoint, a 150,011-character state sent to cloudflare/clef-flash came back 200 and was billed exactly 24,576 input tokens — the window, with the tail discarded and no error — while a 170,011-character state of the same text was refused outright. cloudflare/clef silently bills 16,384 tokens for anything past that point, whatever the state size. Whether an oversized request is truncated or refused is therefore not something you can rely on, so this API never sends one.
English prose runs at about 5.5 characters per token, which is where the character caps come from, with headroom. JSON, code and non-Latin scripts tokenise denser, so a state can still tokenise above the window and be refused; you get a 413 that names the model’s limit and this state’s token count, not a truncated answer.
A response that returns 200 means the model read the whole state. That was not true before this release, and it is the difference between an answer that can be defended and one that looked fine.
cloudflare/clef-omni reads 65,529 tokens — rather than betting on truncation.The response
Answers are keyed by question id, each with its type and a needsReview flag that is set when the model is less confident than your threshold. The top level repeats the first question as choice, confidence and probabilities so a caller with one question can ignore the map.
Systemone response
{
"ok": true,
"model": "cloudflare/clef-flash",
"degraded": false,
"latencyMs": 412,
"plan": "clef-flash-pro",
"usedToday": 17,
"limit": 2000,
"answers": {
"intent": {
"type": "choice",
"choice": "billing",
"confidence": 0.8126,
"probabilities": { "billing": 0.8126, "technical": 0.118, "cancellation": 0.0694 },
"needsReview": true
},
"urgent": { "type": "noul", "noul": 0.7491, "needsReview": true },
"urgency": {
"type": "score",
"score": 2.4632,
"confidence": 0.4633,
"probabilities": { "0": 0.009, "1": 0.0196, "2": 0.4705, "3": 0.5009 },
"legend": { "0": "whenever", "1": "this week", "2": "today", "3": "immediately" },
"needsReview": true
}
},
"choice": "billing",
"confidence": 0.8126,
"probabilities": { "billing": 0.8126, "technical": 0.118, "cancellation": 0.0694 },
"needsReview": true
}
The playground response
/api/decide answers one entry per question, with option naming the winner. provider says who answered (openrouter for the live model, fallback for the local scorer) and requestId identifies this exact call in our logs.
Both endpoints are fail-closed: when the live model is unreachable, /api/v1/decisions and /api/decide return 502 model_unavailable and nothing is charged. The deterministic lexical scorer is opt-in — send "allowDegraded": true on /api/decide — and every answer it produces carries degraded: true, model: "fallback" and provider: "fallback". It is never returned unlabelled, and the systemone endpoint never degrades at all.
Response
{
"ok": true,
"model": "cloudflare/clef-flash",
"provider": "openrouter",
"degraded": false,
"requestId": "0b6f4f4e-5a1e-4c1e-9d3e-2f6a1c9b7d20",
"latencyMs": 412,
"plan": "free",
"usedToday": 3,
"limit": 25,
"answers": [
{
"id": "intent",
"option": "billing",
"confidence": 0.91,
"probabilities": { "billing": 0.91, "technical": 0.04, "cancellation": 0.05 }
}
]
}
Images
A state can be a list of content parts, so a screenshot can be the thing being decided. Images must be embedded base64 data URLs — data:image/png;base64,…, JPEG or WebP. A remote https:// URL is refused, because the model does not fetch URLs.
Image states and states longer than 8,000 characters need a paid key. A free caller who sends one is told exactly that, rather than being handed a truncated answer.
Image state
{
"state": [
{ "type": "text", "text": "Which category does this receipt belong to?" },
{ "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…" } }
],
"questions": [
{ "id": "kind", "type": "choice", "instructions": "Pick the category", "criteria": { "meals": "food and drink", "travel": "transport and lodging" } }
]
}
Request fields
Every field is validated at the boundary; an invalid request is refused with a message that names the offending value.
- text (or its alias state) — string 3 to 200,000 characters, a JSON object, or a list of content parts. Free requests are capped at 8,000 characters.
- questions — 1 to 8 questions, as an array of
{ id, type, instructions, criteria }or an object keyed by id. Ids must match^[a-z][a-z0-9_]{0,31}$. - questions[].instructions — what to decide, up to 1,500 characters.
- threshold — 0.5 to 1, default 0.85. An answer below it comes back with
needsReview: true. - model — optional.
cloudflare/clef-flashandcloudflare/clefare served directly;jev,jev-latest,kevandkev-latestmean this deployment’s model. Any other name is refused rather than silently swapped. - Body size — 64 KB free, 8 MB with a key. A larger body is refused with 413 before it is parsed.
Errors, by code
Every refusal has the same shape: ok: false, a stable code, and a human-readable error. Branch on the code, not on the sentence — the sentence may be edited for clarity, a code never changes meaning, and new codes are only ever added.
Every answer and every refusal from the two decision endpoints also carries a requestId, in the body and in the x-request-id header — the same value in both. It is the handle support searches by, so quote it instead of the time: a 429 that never reached the model is traceable exactly like a 502 that did. An error message names the field that was refused, never its contents.
| code | status | what it means | remedy |
|---|---|---|---|
invalid_request | 400 | the body is well-formed but not a valid request | read error; it names the field |
invalid_json | 400 | the body is not JSON | send content-type: application/json |
empty_body | 400 | no body where one is required | send the JSON body |
missing_field | 400 | a required field is absent | check the request shape above |
invalid_email | 400 | a field that must be an email address is not one | send a full address |
not_found | 404 | no such route, or no such key on this account | check the path or the key id |
key_missing | 401 | no authorization header on an endpoint that needs one | send Bearer cfl_… |
key_malformed | 401 | the header is there but is not a cfl_… key | copy the key whole, no quotes |
key_unknown | 401 | the key does not exist or has been revoked | issue a new key from /api-keys |
plan_ended | 402 | the paid term on this account has ended | renew on /pricing; the keys switch back on |
credit_exhausted | 402 | the month’s credit is spent — the daily call count is a separate limit | buy a credit pack, or wait for the monthly reset; resetsOn states the date |
quota_exceeded | 429 | today’s decisions for this plan are used up | wait for the daily reset; limit says the plan’s figure |
key_limit | 409 | this plan already holds its maximum number of active keys | revoke one, or move up a plan |
rate_limited | 429 | an address firing faster than the edge will take, as a best-effort burst guard — not a plan limit and not a number to design against | back off for a second and retry |
concurrency_exceeded | 429 | more requests in flight than the plan allows | wait for one of your own calls to finish; retry-after is 1 |
payload_too_large | 413 | the body is past the byte cap | the message states both numbers |
state_too_large | 413 | the state is past what the model you named reads | shorten the state, or name a larger model |
model_rejected | 400 | the provider refused this request upstream | the message carries the provider’s reason |
model_unavailable | 502 | the model could not be reached | nothing was charged; retry |
model_not_configured | 503 | this deployment has no model configured | retrying will not help; write to us |
gateway_not_configured | 503 | the payment gateway is not provisioned | retry after a minute; we are already alerted |
internal_error | 500 | anything we did not classify | retry once, then write to us with the time |
quota_exceeded clears at the daily reset, rate_limited clears in a minute, and concurrency_exceeded clears the moment one of your own calls finishes — retrying it immediately is the one thing that will not work.Quotas, by plan
A plan sells decisions per day and requests in flight at the same time. It does not sell a request rate: throughput is concurrency divided by latency, so eight requests in flight against a 1.3-second answer is about six answers a second — that is the model’s speed, not a limit we impose. A faster model, or a shorter state, raises it without a plan change.
The free tier counts per browser session per day; paid tiers count per API key per day. Every answer reports usedToday and limit, and GET /api/v1/usage reports the whole table below for the key you are asking with, so a client can pace itself instead of discovering a limit at a 429.
| plan | decisions / day | requests in flight | body cap | state cap | images | keys |
|---|---|---|---|---|---|---|
| playground (no key) | 25 per session | not capped | 64 KB | 8,000 chars | none | — |
| Pro | 2,000 | 8 | 8 MB | 200,000 chars | 4 | 1 |
| Scale | 20,000 | 32 | 8 MB | 200,000 chars | 4 | 3 |
| Studio | 40,000 | 64 | 8 MB | 200,000 chars | 4 | 10 |
| Agency | 100,000 | 128 | 8 MB | 200,000 chars | 4 | 40 |
concurrency_exceeded from then on. That date is on /log. Batch tip: put several independent questions about the same state in one request — it costs one decision, not one per question.Usage credit, defined
Credit measures model time, not calls. One call carrying a long state costs more than one carrying a short state, so a call count alone cannot stop the endpoint running at a loss — credit is the second limit that does. Both limits are checked on every request and they are independent: whichever is exhausted first is the refusal you get. quota_exceeded is the daily call count; credit_exhausted is the month’s model time, and it can arrive while the daily count still has room.
One credit is $0.50 of model time. At $0.019 per million input tokens that is 26.3 million input tokens — about 26,315 calls carrying 1,000 tokens each.
A plan’s allowance resets on the first day of the calendar month and never carries over. A credit pack is bought once, never expires, and pays only for calls that run past the month’s allowance. Packs: Pack S 10 credits ($5.00 of model time), Pack M 52 credits ($26.00 of model time), Pack L 220 credits ($110.00 of model time), Pack XL 900 credits ($450.00 of model time). A refused request never reaches the model, is not metered and is not charged.
Every answer carries a credit block — period, reset date, included, used, remaining. GET /api/v1/usage returns the same block plus creditUnit, which states what a credit is worth in dollars, input tokens and calls, so a client can convert a usage figure without reading this page. The 402 body repeats the figures and adds topUpUrl and usageUrl.
| plan | credit / month | model time included |
|---|---|---|
| Pro | 6 | $3.00 |
| Scale | 40 | $20.00 |
| Studio | 72 | $36.00 |
| Agency | 180 | $90.00 |
Your first request, in JavaScript and Python
Both programs below are complete. Save one, set CLEF_FLASH_KEY to the key emailed with your order, and run it: Node 18 or newer for the first, Python 3.9 or newer for the second, no package to install. A successful run prints the winning label, the full distribution and the requestId support needs to trace the call.
Each reads CLEF_FLASH_URL when it is set, so the same file runs against a local wrangler dev without edits. Run them on a server or in a job, never in a browser: a browser would hand the key to every visitor. Without a key yet, the playground runs the same model free.
The suite builds the request from the same definition these snippets carry, then executes both programs unchanged against the real handler over HTTP and fails the build if either stops returning a usable answer. The code on this page is the code that runs.
JavaScript (Node 18+)
const key = process.env.CLEF_FLASH_KEY;
if (!key) throw new Error('Set CLEF_FLASH_KEY to the key emailed with your order.');
const base = process.env.CLEF_FLASH_URL ?? 'https://clef-flash.com';
const response = await fetch(`${base}/api/v1/decisions`, {
method: 'POST',
headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
body: JSON.stringify({
"text": "Customer wrote: I was charged twice for the October invoice.",
"questions": [
{
"id": "intent",
"type": "choice",
"instructions": "What does the customer want?",
"criteria": {
"billing": "a charge, invoice or refund",
"technical": "something is broken or misbehaving",
"cancellation": "they want to stop paying"
}
}
]
}),
});
const payload = await response.json();
if (!response.ok || payload.ok !== true) {
console.error(payload.code ?? response.status, payload.error ?? 'request failed');
process.exit(1);
}
const answer = payload.answers.intent;
console.log(answer.choice, answer.probabilities, `requestId=${payload.requestId}`);
Python 3.9+
import json
import os
import sys
import urllib.error
import urllib.request
key = os.environ.get("CLEF_FLASH_KEY")
if not key:
sys.exit("Set CLEF_FLASH_KEY to the key emailed with your order.")
base = os.environ.get("CLEF_FLASH_URL", "https://clef-flash.com")
request = urllib.request.Request(
base + "/api/v1/decisions",
data=json.dumps({
"text": "Customer wrote: I was charged twice for the October invoice.",
"questions": [
{
"id": "intent",
"type": "choice",
"instructions": "What does the customer want?",
"criteria": {
"billing": "a charge, invoice or refund",
"technical": "something is broken or misbehaving",
"cancellation": "they want to stop paying"
}
}
]
}).encode(),
method="POST",
headers={"content-type": "application/json", "authorization": "Bearer " + key},
)
try:
with urllib.request.urlopen(request, timeout=30) as response:
payload = json.load(response)
except urllib.error.HTTPError as error:
payload = json.load(error)
print(payload.get("code", error.code), payload.get("error", "request failed"), file=sys.stderr)
sys.exit(1)
answer = payload["answers"]["intent"]
print(answer["choice"], answer["probabilities"], "requestId=" + payload["requestId"])
A successful first run prints
- The winning label — one of billing, technical or cancellation.
- The distribution over all three labels, summing to 1.
- requestId=… — the id to quote when asking support about that call.
When to prefer self-hosting
If the state contains data that cannot leave your infrastructure, run the model yourself — the weights are Apache 2.0. The run-locally guide covers the hardware and the Ollama command. The request shape is the same, so the code you write against this API ports directly.
Community-hosted demo of the 9B model. Runs live in your browser session.
Frequently asked questions
Do I need an API key?
For /api/v1/decisions, yes. The playground /api/decide works without one, counted per browser session; a paid key raises the daily quota on both and lifts the body cap to 8 MB.
Can I point an existing jevapi client at this endpoint?
Yes, by changing the base URL. State as an object, questions keyed by id, criteria per question and a jev-latest or kev model name are all accepted as sent. The answer map uses the same ids and types, noul answers carry the same noul field; the top-level summary and the extra ok/latency/plan fields are additive.
Is the response cached?
No. Every request runs the model. Identical requests are not de-duplicated, so avoid polling the same state in a loop.
Which model answers?
Clef-Flash by default. The response names the model actually used and the provider that answered. Both endpoints are fail-closed: a provider failure is a 502 model_unavailable, never a guess. The deterministic fallback answers only when a /api/decide caller sends "allowDegraded": true, and then reports degraded: true and provider: "fallback".
Need a higher quota?
Paid plans raise the daily limit and issue an API key. See the pricing page, or write to us for volume.