Foretell API — Developer Docs

1. Credits — one balance, no plans

There are no API plan tiers. Every API key draws from the same prepaid credit wallet as the Web App. 1 credit = 1 simulation = $199 and credits never expire. Buy credits in the Web App (foretell.technology/credits); the developer key spends from that wallet. Referral credit works the same way: the referral program adds $100 to each side (credit only, never cash) straight into this wallet, and API jobs spend it like any other balance.

2. Issue a key (free, instant)

Create an account / log in to get a session token (ft_sess_…).
Issue a key — instant, no payment, no tier to choose:

curl -X POST https://api.foretell.technology/v1/keys \
  -H "Authorization: Bearer $FT_SESSION" \
  -H "Content-Type: application/json" \
  -d '{"name":"my first key"}'
# → { "api_key": "ft_live_…", "plan": "live", "warning": "shown only once" }

3. Submit a job (deducts 1 credit)

A job IS a simulation, framed async: it deducts $199 on submission and returns immediately with job_id, status:"queued" and balance_remaining. The sim runs in the background (up to 24h) at the full 1000-agent depth.

curl -X POST https://api.foretell.technology/v1/jobs \
  -H "Authorization: Bearer ft_live_…" \
  -H "Idempotency-Key: launch-2026-06-15-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pricing change","scenario":"We are raising prices 20% next month."}'
# → 202 { "job_id":"…", "status":"queued", "paid_via":"credit",
#         "sim_cost_usd":199, "balance_remaining": 796.0,
#         "status_url":"/v1/jobs/…/status", "report_url":"/v1/jobs/…/report" }
# 402 insufficient_credits when the wallet is short (buy more credits).

4. Poll status, then fetch the report

curl https://api.foretell.technology/v1/jobs/$ID/status \
  -H "Authorization: Bearer ft_live_…"     # status: queued→running→completed

curl https://api.foretell.technology/v1/jobs/$ID/report \
  -H "Authorization: Bearer ft_live_…"     # report JSON + attribution block

A job that fails after starting is refunded automatically.

5. What’s inside the report JSON

The report is the FULL analysis — the same depth Web App customers see: headline, risk_score, confidence (+ confidence_basis), cohort_breakdowns, failure_modes, mitigations, counter_narratives, sentiment_trajectory, quantitative_forecast (when your scenario carries a numeric metric), plus report_schema_version and the attribution block. Two sections generate automatically at no extra charge:

plain_language_summary — a few jargon-free paragraphs ({"paragraphs": ["…"]}) synthesized from the completed analysis: what was found and who reacted, the human impact, the business impact, alternatives tested, and the recommendation. Present in every new report.
ideal_solution — appended automatically when the simulation comes back Medium or High risk: four to six alternative approaches are screened and the single winner is confirmed with a full 1,000-agent run, inside the same 24-hour turnaround. On Low-risk reports the field records that no alternatives were needed.

Linked Reports & the Decision Tiebreaker — now in /v1: combine two or more of your completed reports into one cross-analysis ($25 per linked report from the same wallet; ranked mode recommends a winner, compare mode deliberately names none), then optionally resolve a close compare-mode call with the Tiebreaker add-on ($75 flat).

GET  /v1/links/linkable         # completed reports you can link
POST /v1/links                  # {"scenario_ids":["…","…"], "mode":"ranked"|"compare", "name":"…"}
                                # 201 → {link_group_id, cost_usd, …} · 402 when the wallet is short
GET  /v1/links                  # your link groups
GET  /v1/links/{id}             # status: pending → running → complete
GET  /v1/links/{id}/report      # plain_language_summary + cross-analysis + full member reports (?lang=xx)
POST /v1/links/{id}/tiebreaker  # compare-mode links only, after completion; 409 otherwise

6. Check your balance

curl https://api.foretell.technology/v1/credits \
  -H "Authorization: Bearer ft_live_…"
# → { "balance_usd": 796.0, "sim_cost_usd": 199, "sims_available": 4,
#     "transactions": [ … last 10 … ] }

7. Webhooks (HMAC-signed)

Register an HTTPS endpoint; you'll get scenario.completed / scenario.failed events signed Foretell-Signature: t=<unix>,v1=<hmac_sha256(secret,"t.body")>. Verify the MAC over "{t}.{raw_body}" and reject stale timestamps.

curl -X POST https://api.foretell.technology/v1/webhooks \
  -H "Authorization: Bearer ft_live_…" \
  -d '{"url":"https://you.example/hook","events":["scenario.completed"]}'
# → { "secret": "whsec_…" }   # store now

8. Credit packages & the badge

Package	Credits	Price	Per credit
Single	1	$199	$199
Pack 5	5	$795	$159
Pack 10	10	$1,290	$129
Pack 25	25	$2,475	$99

Every report must display “Powered by Enterprise.Systems” wherever report content is shown; hosted report pages render it server-side.

Auth: pass your key as Authorization: Bearer ft_live_… or the X-API-Key header. Rate limit: 120 requests/min per key (a 429 with Retry-After when exceeded).

Machine-readable spec: /openapi.json · Balance, idempotency and rate limits appear in GET /v1/usage and GET /v1/credits.

1. קרדיטים — יתרה אחת, בלי מסלולים

אין מסלולי API. כל מפתח מושך מאותו ארנק הקרדיטים המשולם-מראש של אפליקציית הווב. קרדיט אחד = סימולציה אחת = $199, והקרדיטים לא פגים. רוכשים קרדיטים באפליקציית הווב (foretell.technology/credits), ומפתח המפתחים מוציא מאותו ארנק. קרדיט הפניה עובד באותו אופן: תוכנית ההפניות מזכה $100 לכל צד (קרדיט בלבד, לעולם לא מזומן) ישירות לארנק הזה, ו-jobs של ה-API מוציאים אותו כמו כל יתרה אחרת.

אימות: העבירו את המפתח כ-Authorization: Bearer ft_live_… או ב-X-API-Key. מגבלת קצב: 120 בקשות/דקה למפתח (429 עם Retry-After בחריגה).

2. הנפקת מפתח (חינם, מיידי)

פתחו חשבון / התחברו וקבלו אסימון סשן (ft_sess_…).
הנפיקו מפתח — מיידי, ללא תשלום, בלי לבחור מסלול:

curl -X POST https://api.foretell.technology/v1/keys \
  -H "Authorization: Bearer $FT_SESSION" \
  -d '{"name":"my first key"}'
# → { "api_key": "ft_live_…", "plan": "live" }

3. שליחת job (מנכה קרדיט אחד)

job הוא סימולציה במצב אסינכרוני: מנכה $199 בעת השליחה ומחזיר מיד job_id, status:"queued" ו-balance_remaining. הסימולציה רצה ברקע (עד 24 שעות) בעומק מלא של 1000 סוכנים.

curl -X POST https://api.foretell.technology/v1/jobs \
  -H "Authorization: Bearer ft_live_…" \
  -H "Idempotency-Key: launch-001" \
  -d '{"name":"שינוי מחיר","scenario":"אנחנו מעלים מחירים ב-20% בחודש הבא."}'
# → 202 { "job_id":"…", "status":"queued", "balance_remaining": 796.0 }
# 402 insufficient_credits כשהיתרה נמוכה (רכשו עוד קרדיטים).

4. בדיקת סטטוס ושליפת הדוח

curl …/v1/jobs/$ID/status   # queued→running→completed
curl …/v1/jobs/$ID/report   # JSON של הדוח + בלוק ייחוס

job שנכשל אחרי שהתחיל — הקרדיט מוחזר אוטומטית.

5. מה יש בתוך ה-JSON של הדוח

הדוח הוא הניתוח המלא — אותו עומק שרואים לקוחות אפליקציית הווב: headline, risk_score, confidence (+confidence_basis), cohort_breakdowns, failure_modes, mitigations, counter_narratives, sentiment_trajectory, quantitative_forecast (כשהתרחיש כולל מדד מספרי), ובנוסף report_schema_version ובלוק הייחוס. שתי סקציות נוצרות אוטומטית ללא תוספת מחיר:

plain_language_summary — כמה פסקאות בשפה פשוטה ({"paragraphs": ["…"]}) המסונתזות מהניתוח שהושלם: מה נמצא ומי הגיב, ההשפעה על אנשים, ההשפעה העסקית, חלופות שנבחנו, וההמלצה. קיים בכל דוח חדש.
ideal_solution — מתווסף אוטומטית כשסימולציה חוזרת בסיכון בינוני או גבוה: ארבע עד שש גישות חלופיות נבחנות והמנצחת היחידה מאושרת בהרצה מלאה של 1,000 סוכנים, בתוך אותן 24 שעות. בדוחות בסיכון נמוך השדה מתעד שלא נדרשו חלופות.

דוחות מקושרים ומכריע ההחלטה — עכשיו גם ב-/v1: שלבו שני דוחות שהושלמו או יותר לניתוח צולב אחד ($25 לכל דוח מקושר מאותו ארנק; מצב ranked ממליץ על מנצחת, מצב compare במכוון לא בוחר), ולאחר השלמת דוח compare אפשר להפעיל את מכריע ההחלטה ($75 קבוע).

GET  /v1/links/linkable         # completed reports you can link
POST /v1/links                  # {"scenario_ids":["…","…"], "mode":"ranked"|"compare", "name":"…"}
                                # 201 → {link_group_id, cost_usd, …} · 402 when the wallet is short
GET  /v1/links                  # your link groups
GET  /v1/links/{id}             # status: pending → running → complete
GET  /v1/links/{id}/report      # plain_language_summary + cross-analysis + full member reports (?lang=xx)
POST /v1/links/{id}/tiebreaker  # compare-mode links only, after completion; 409 otherwise

6. בדיקת יתרה

curl https://api.foretell.technology/v1/credits \
  -H "Authorization: Bearer ft_live_…"
# → { "balance_usd": 796.0, "sims_available": 4, "transactions": [ … ] }

7. Webhooks (חתומים ב-HMAC)

רשמו endpoint ב-HTTPS ותקבלו אירועי scenario.completed/scenario.failed חתומים. אמתו את ה-MAC על "{t}.{body}" ודחו חותמות זמן ישנות.

8. חבילות קרדיטים והתג

חבילה	קרדיטים	מחיר	לקרדיט
בודד	1	$199	$199
חבילת 5	5	$795	$159
חבילת 10	10	$1,290	$129
חבילת 25	25	$2,475	$99

כל דוח חייב להציג “Powered by Enterprise.Systems” בכל מקום שבו מוצג תוכן הדוח; עמודי הדוח המתארחים מציגים זאת בצד השרת.