Guides
Decisions
View as MarkdownOn this page
A decision is a closed question answered from the press EarlyWave reads, with a typed value, a certainty and the articles behind it. Ask whether something happened (noul, yes/no), which of a few options holds (choice), how far along a scale (score), or anything in a sentence (text). One call, up to 20 questions, the same evidence for all of them.
| REST | MCP tool | Returns |
|---|---|---|
POST /decisions | decide | One typed answer per question, the numbered sources and what the call cost. |
What the evidence is
The state names where the answers come from. At least one of:
| Field | Evidence |
|---|---|
query | A search of the whole corpus (every source EarlyWave reads, the last 15 days): the matching articles. |
source_ids | Articles by id, from any list of this API (30 at most). |
trend_id | The latest articles of a trend. |
monitor_id | The latest results of one of your monitors, with their sources. |
The engine reads the evidence only. When the articles neither affirm nor deny a statement, the answer abstains (abstained: true, band: "abstained") — the absence of news is not a no.
A first decision
curl -X POST "https://api.earlywave.ai/api/v1/decisions" \
-H "Authorization: Bearer $EARLYWAVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"questions": [
{ "text": "Has Atos announced a layoff plan this month?", "type": "noul" },
{ "text": "Which company announced the largest plan?", "type": "choice", "options": ["Atos", "Ubisoft", "Renault"] },
"What did the unions say?"
],
"state": { "query": "plan social" },
"language": "en"
}'{
"decision_id": "7a3c2d1e-5b6f-4e8a-9c0d-1f2e3a4b5c6d",
"answers": [
{
"idx": 0,
"question": "Has Atos announced a layoff plan this month?",
"type": "noul",
"value": true,
"probability": 0.91,
"probabilities": null,
"band": "very_likely",
"abstained": false,
"provenance": "corpus",
"flags": [],
"answer": "The group confirmed a plan of 500 positions on 14 October.",
"sources": [1, 3]
},
{
"idx": 1,
"question": "Which company announced the largest plan?",
"type": "choice",
"value": "Atos",
"probability": 0.72,
"probabilities": { "Atos": 0.72, "Ubisoft": 0.21, "Renault": 0.07 },
"band": "likely",
"abstained": false,
"provenance": "corpus",
"flags": [],
"answer": "Atos names 500 positions, Ubisoft 185; nothing on Renault.",
"sources": [1, 2]
},
{
"idx": 2,
"question": "What did the unions say?",
"type": "text",
"value": null,
"probability": null,
"probabilities": null,
"band": "likely",
"abstained": false,
"provenance": "corpus",
"flags": [],
"answer": "The CGT called the plan disproportionate and asked for talks.",
"sources": [3]
}
],
"sources": [
{ "n": 1, "id": 9917305, "title": "Atos confirms 500 job cuts", "url": "https://…", "publisher": "Les Echos", "published": "2026-10-14T06:10:00.000Z" },
{ "n": 2, "id": 9918120, "title": "Ubisoft to cut 185 positions", "url": "https://…", "publisher": "Le Monde", "published": "2026-10-16T08:40:00.000Z" },
{ "n": 3, "id": 9918411, "title": "Unions react to the Atos plan", "url": "https://…", "publisher": "L'Usine Nouvelle", "published": "2026-10-15T11:02:00.000Z" }
],
"usage": { "credits": 0.3, "api_requests_remaining": 9987 },
"web": { "requested": "off", "ran": false }
}A question written as a plain string is a free (text) question.
Reading an answer
| Field | Meaning |
|---|---|
value | noul: true, false, or null when uncertain. choice: the option. score: the probability-weighted mean level, from 0 to levels.length − 1. text: null, the prose is in answer. |
probability | noul: p(true). choice and score: the probability of the chosen option or modal level. |
probabilities | choice: by option. score: by level index ("0", "1", …). |
band | very_likely (≥ 0.85), likely (≥ 0.60), uncertain (≥ 0.40), unlikely (≥ 0.15), very_unlikely, or abstained. A yes/no reads Yes from 0.60, No under 0.40, uncertain between. |
abstained | The sources neither affirm nor deny it. A result of its own. |
answer | The whole answer of a free question; one sentence of justification for a typed one. |
sources | The n of the sources behind this answer. |
Route uncertain and abstained answers to a person; act on very_likely and very_unlikely ones.
What it costs
A decision is one request in the two counters of the API (the minute window, the monthly quota) and 0.3 credit on the account's wallet when the engine runs on the corpus. The X-Credits-Used header and usage.credits say it. Nothing is consumed when the call is refused: an invalid body (400), no credits left (402, error.type = payment, error.code = credits_exhausted), the counters (429). A call with no evidence (nothing matched) costs 0 and every answer abstains.
The web
web accepts off (default), if_thin and on, so your client can already send the shape. The web leg is not available yet: if_thin and on answer 400 web_unavailable. On a trial key they answer 403 web_not_in_trial.
Developer trial
An account without API access can create one trial key from Settings › API & MCP: 30 days, 10 requests a minute, 100 requests a day across every operation (the X-Quota-* headers then describe the day), of which 20 decisions a day (429 decisions_quota_exceeded after), the corpus only, no credits.
In the app
The same engine answers the standing questions of your monitors (typed, with a history) and the decide tool of Ask EarlyWave; get_monitor_results returns the current answers.