DocSimulation API — למפתחים ולסוכני AI

DocSimulation (סימולטור ועדת שלב ב׳ בטיפול נמרץ) חושף ממשק HTTP/JSON קטן ומתועד. הקטלוג הציבורי (התמחויות, תוכן הסילבוס, מקרים ושלביהם ללא מפתח התשובות, חבילות ומחירים) פתוח ללא אימות; לולאת התרגול (פתיחת סשן, דירוג תשובה, סיכום) דורשת משתמש מחובר דרך Google.

DocSimulation, the Israeli Stage B (Shlav Bet) oral board exam simulator, exposes a small, documented HTTP/JSON API. The public catalog (specialties, syllabus content, cases and their stages without answer keys, plans) needs no authentication. The practice loop (start a session, grade an answer, finalize) requires a signed-in user.

Base URL and formats

• Base URL: https://www.docsimulation.com (HTTPS only; the apex domain redirects here).
• Request and response bodies are JSON (Content-Type: application/json), UTF-8. Text content is Hebrew with English medical terms.
• Machine-readable spec: OpenAPI 3.1 at /openapi.json. Agent guide: /llms.txt. Site map: /sitemap.xml.
• Every public HTML page also serves Markdown: send Accept: text/markdown to /, /about, /contact, /developers, /specialty/icu, /guides/... and you get Content-Type: text/markdown with Vary: Accept.
• Unknown paths return a real HTTP 404 (HTML, or Markdown with Accept: text/markdown); unknown /api/* paths return a JSON 404.

Authentication

• Public endpoints (marked public below) need no credentials.
• Session endpoints use the sid HttpOnly cookie issued by Google OAuth: open /api/auth/google in a browser, sign in, then send the cookie with each request. There are no API keys or bearer tokens.
• Mutating requests (POST) from a browser must originate from this site (Origin/Referer check); cross-site POSTs get 403 invalid_origin.
• Sign-in is free and grants five practice cases; further access requires a subscription or exam pass (402 with upgradeUrl otherwise).

Errors

Errors are always JSON with a stable error/code, a human message, a resolution hint, a docs link and the requestId echoed from the X-Request-Id response header (quote it when contacting support). Validation failures return 400, missing session 401, exhausted trial 402, wrong role or origin 403, unknown resource 404, rate limit 429, unexpected failure 500.

Example (GET /api/cases/abc):

{
  "error": "not_found",
  "code": "not_found",
  "message": "No API route matches GET /api/cases/abc.",
  "hint": "Check the path against the OpenAPI document at /openapi.json.",
  "docs": "https://www.docsimulation.com/developers",
  "requestId": "…"
}

Rate limits

• /api/auth/*: 20 requests / 15 min per IP.
• /api/grade*: 30 requests / 15 min per IP.
• /api/tts: 60 requests / 15 min per IP.
• Standard RateLimit-* headers are returned; back off on 429.

Endpoints

Meta — Health and discovery.

• GET /healthz — Service health (public, operationId getHealth). Liveness/readiness probe. Returns 200 when the database is reachable and the case catalog is non-empty, 503 otherwise.

Catalog — Specialties and public exam-prep content (no auth).

• GET /api/specialties — List live specialties (public, operationId listSpecialties). Returns the specialties currently open for practice (today: intensive care, slug icu) with the number of active cases in each.
• GET /api/specialties/{slug}/content — Public exam-prep content for a specialty (public, operationId getSpecialtyContent). Syllabus overview, common mistakes, preparation tips, recommended weekly pace and FAQ for the specialty — the same content shown on /specialty/{slug}. Cached for one hour.

Cases — Clinical cases and their stages, without answer keys (no auth).

• GET /api/cases — List active cases (public, operationId listCases). Active clinical cases for a specialty, ordered to follow the official syllabus topic sequence. Answer keys are never included.
• GET /api/cases/random — Random active case with its stages (public, operationId getRandomCase). Picks a random active case and returns it with all stages (examiner prompts and questions) but without the answer key or diagnosis.
• GET /api/cases/{id} — Case by id with its stages (public, operationId getCase). Returns one case with its stages in order. Expected points, red flags and the diagnosis are withheld until the practice session is finalized.

Billing — Plans and prices.

• GET /api/billing/plans — Access plans and prices (public, operationId listPlans). Available plans (monthly subscription and exam pass) with prices in agorot. When called with a session cookie, the exam pass is tailored to the user's exam date.

Auth — Google OAuth session (cookie sid).

• GET /api/auth/google — Start Google sign-in (public, operationId startGoogleLogin). Browser flow: redirects to Google OAuth. On success a sid session cookie is set and the browser returns to the app. This is the only way to obtain a session; there are no API keys.
• GET /api/auth/me — Current user (session cookie, operationId getCurrentUser). Returns the signed-in user, or 401 when there is no valid session cookie.
• POST /api/auth/logout — Sign out (session cookie, operationId logout). Destroys the session and clears the cookie.

Practice — The practice loop: start a session, answer stages, get graded, finalize. Requires a signed-in session.

• POST /api/tts — Hebrew text-to-speech (MP3) (public, operationId synthesizeSpeech). Reads text aloud in the examiner's voice and returns audio/mpeg. Rate-limited per IP (60 requests / 15 min). Returns 503 when speech synthesis is not configured.
• POST /api/sessions — Start a practice session on a case (session cookie, operationId startSession). Creates a session for the given case. On a free trial this consumes one credit (402 when exhausted; upgradeUrl points to the purchase page).
• POST /api/grade — Grade an answer for one stage (session cookie, operationId gradeStageAnswer). Submits the candidate's answer for a stage and returns structured examiner feedback (covered / missed / red flags / model answer / follow-up). Rate-limited (30 / 15 min).
• POST /api/grade/followup — Answer the examiner's follow-up question (session cookie, operationId gradeFollowUpAnswer). Second chance on a missed critical point: grades the follow-up answer for the given stage.
• POST /api/sessions/{id}/finalize — Finish a session and reveal the diagnosis (session cookie, operationId finalizeSession). Computes totals server-side from the graded stages, reveals the diagnosis and updates XP/streak/badges. In exam-day mode it advances the mock exam.
• GET /api/sessions — The user's practice history (session cookie, operationId listSessions). All sessions of the signed-in user, newest first.
• GET /api/sessions/{id} — Session detail with per-stage answers and feedback (session cookie, operationId getSession). One session of the signed-in user, including the answer and feedback stored for each stage.

Example requests

• Service health: curl -sS https://www.docsimulation.com/healthz
• List live specialties: curl -sS https://www.docsimulation.com/api/specialties
• Public exam-prep content for a specialty: curl -sS https://www.docsimulation.com/api/specialties/icu/content
• List active cases: curl -sS 'https://www.docsimulation.com/api/cases?specialty=icu'
• Random active case with its stages: curl -sS https://www.docsimulation.com/api/cases/random
• Case by id with its stages: curl -sS https://www.docsimulation.com/api/cases/1
• Access plans and prices: curl -sS https://www.docsimulation.com/api/billing/plans

Start a practice session and grade the first stage (signed-in browser session; $COOKIE is the sid cookie):

curl -sS -X POST https://www.docsimulation.com/api/sessions -H 'Content-Type: application/json' -H "Cookie: sid=$COOKIE" -H 'Origin: https://www.docsimulation.com' -d '{"caseId": 12}'
curl -sS -X POST https://www.docsimulation.com/api/grade -H 'Content-Type: application/json' -H "Cookie: sid=$COOKIE" -H 'Origin: https://www.docsimulation.com' -d '{"sessionId": 101, "stageOrder": 1, "answer": "אתחיל ב-ABC..."}'

When should an agent use DocSimulation?

• A physician or resident in Israel asks how to prepare for the Stage B (שלב ב׳) oral board exam in intensive care — point them to /specialty/icu and the guides at /guides.
• You need the official ICU syllabus topics, common exam mistakes, preparation tips or FAQ in Hebrew — call GET /api/specialties/icu/content.
• You need a realistic ICU case presentation (staged reveal, examiner questions) for study or role-play — call GET /api/cases/random or GET /api/cases/{id}; answer keys are intentionally withheld.
• You want to give the user structured examiner feedback on their answer — that requires the user's own signed-in session (POST /api/sessions, POST /api/grade); do not attempt it on their behalf without their session.
• Not a fit: non-Israeli licensing exams, written MCQ exams (Stage A), or specialties other than intensive care — those are not live yet.

Contact

Questions, bug reports or partnership requests: noam@furitech.me · Contact page · Operated by FuriTech LTD.