HTTP API

Base URL https://api.scientistworkbench.com. Every request carries Authorization: Bearer wb_…. JSON in, JSON out; POST /jobs is multipart so files can ride along.

1. Submit a job — POST /jobs → 202

Multipart form with one field spec (JSON string) and zero or more files parts.

{
  "prompt": "Take this data from the CRO and QC it and return a summary of the results.",
  "company": "Acme Bio",
  "entity_id": "programs/study-01",
  "inputs": [{"name": "plate.xlsx", "base64": "…"}, {"name": "ref.csv", "url": "https://…/ref.csv"}],
  "source_refs": [], "metric_keys": [], "entity_hints": [], "evidence_date": "2026-09-01",
  "caller": "my-agent",
  "options": {"job_class": "specialist", "reviewer": true, "input_policy": "auto", "timeout_minutes": null}
}

• prompt (required) — one task per job; say what to compute and what to return.
• company (required, free label) and entity_id (optional) group jobs for your own bookkeeping.
• inputs[] — each item is exactly one of base64 (≤ 20 MB inline) or url (https, fetched server-side, ≤ 500 MB). Large files can also be sent as multipart files parts (≤ 600 MB).
• options.job_class — specialist (default) | lookup | research. reviewer (default true) runs the independent review pass. input_policy — auto (the agent picks the standard, defensible option when it would otherwise need to ask; default) or fail. timeout_minutes overrides the class backstop (1–720).

Response: {"job_id": "sci-20260914-…", "status": "queued"}.

Errors: 401 bad key · 402 {"error":"insufficient_credits"} · 422 bad spec · 429 concurrency or rate limit.

2. Follow it

• GET /jobs/{id} → status: queued → staging → submitting → running → harvesting → extracting → done, or failed | cancelled | timed_out. Includes last_text, status_description, last_event_seq.
• GET /jobs/{id}/events?since=N&wait=25 → long-poll for new events (state, text, tool_use, artifact, reviewer, warning, usage, error); wait blocks up to 25 s until something arrives.
• POST /jobs/{id}/cancel → 202; the job stops, whatever was saved is harvested and returned.

3. Read the result — GET /jobs/{id}/result

409 {"status": "running"} until terminal, then:

{
  "job_id": "sci-…", "status": "done",
  "summary_md": "# QC of …\n## Objective …", "summary_source": "artifact",
  "artifacts": [{"filename": "fig1.png", "mime": "image/png", "sha256": "…", "size": 341279, "kind": "figure",
                 "ref": "science:sci-…/fig1.png"}],
  "reviewer_findings": [{"verdict": "warn", "status": "unaddressed", "severity": "medium",
                         "claim": "…", "evidence": "…"}],
  "usage": {"seconds": 658.5, "input_tokens": 79, "output_tokens": 40386},
  "engine": {"name": "sandbox", "model": "standard model", "status": "terminated"},
  "billing": {"metered": true, "tokens_debited": 185000, "balance_after_tokens": 2142000},
  "warnings": [], "error": null,
  "disclosure": "AI-generated analysis. …"
}

• summary_md is the report the agent wrote (Objective · Method · Results · Assumptions & caveats · Files). Links inside it use science:<job_id>/<filename> references that map to the artifact endpoint below.
• reviewer_findings come from an independent pass over the execution record; treat warn/fail as things a scientist should look at before using the number.
• _execution_log.json (an artifact) lists every command the agent ran with stdout/stderr, for provenance.

4. Download artifacts — GET /jobs/{id}/artifacts/{filename}

Responds with a 307 to a signed, short-lived download link; follow redirects. 410 after the 90-day artifact retention window (the result document itself never expires).

5. Account — GET /me

Tenant profile, balance_tokens, recent ledger, active job count. GET /jobs?company=&limit= lists your jobs.

6. How an agent should use this

1. One task per job. Put the question, the deliverables you expect, and any thresholds in prompt.
2. Attach the data (inputs[] or multipart). Don't paste tables into the prompt.
3. Submit, then poll /events with wait=25 (or /jobs/{id} every 20–30 s). Typical jobs take 5–40 minutes.
4. Read summary_md for the narrative and artifacts for the numbers; cite artifacts by their ref.
5. Surface reviewer_findings with the answer; never drop a fail.
6. Keep the job_id: results are re-readable later by id.