API Documentation

POST /api/toxscreen/v1/screen

Submit a compound for toxicity screening with your tsk_ API key (X-API-Key header). Scoring is synchronous: predictions run inline on CPU (deterministic ADMET-AI, ~1–7 seconds per compound), so the response already carries the final status — there is no queue to poll.

Parameters

Example request

curl -X POST https://toxscreen.ai/api/toxscreen/v1/screen \
  -H "X-API-Key: tsk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "smiles": "COc1ccc(CCN2CCC(CC2=O)c3ccc(F)cc3)cc1",
    "name": "Compound-42",
    "panel": "full"
  }'

Example response

{
  "job_id": "ts_job_a1b2c3d4e5f6",
  "status": "completed",
  "queue_position": 0,
  "eta_minutes": 0,
  "compound_name": "Compound-42",
  "panel": "full"
}

The job is already completed on return (queue_position and eta_minutes are always 0). Fetch the rich per-target record from GET /v1/jobs/{job_id}/result. Browser/session clients can call POST /jobs with the same body and a Bearer session token for identical behaviour.

GET /api/toxscreen/v1/jobs/{id}

Retrieve the status and headline metrics for a job. Accepts X-API-Key header or session JWT (Bearer). For the full per-target record, call GET /v1/jobs/{id}/result.

Example request

curl https://toxscreen.ai/api/toxscreen/v1/jobs/ts_job_a1b2c3d4e5f6 \
  -H "X-API-Key: tsk_..."

Example response (completed)

{
  "id": "ts_job_a1b2c3d4e5f6",
  "compound_name": "Compound-42",
  "compound_smiles": "COc1ccc(CCN2CCC(CC2=O)c3ccc(F)cc3)cc1",
  "panel": "full",
  "status": "completed",
  "report_available": true,
  "error_message": null,
  "created_at": "2026-06-20T14:30:00+00:00",
  "completed_at": "2026-06-20T14:30:05+00:00",
  "cti": 0.31,
  "risk_level": "MODERATE",
  "per_target_bp": {
    "7CN1": 0.12,
    "6MA7": 0.45,
    "4WNT": 0.28,
    "1OG5": 0.09
  }
}

per_target_bp is a map keyed by PDB id (7CN1 = hERG, 6MA7 = CYP3A4, 4WNT = CYP2D6, 1OG5 = CYP2C9). For queued/running/failed jobs the metric fields are omitted. The summary metrics (cti, risk_level, per_target_bp) appear only when status is completed.

GET /api/toxscreen/v1/jobs/{id}/result

Return the structured JSON result record for a completed job — the full per-target ADMET payload including calibrated probabilities, Wilson 80%/95% confidence intervals, applicability-domain confidence/abstention flags, extended ADMET panel (CYP1A2, HIA, BBB, Ames, etc.), CTI and risk level. Accepts X-API-Key or Bearer JWT.

Example request

curl https://toxscreen.ai/api/toxscreen/v1/jobs/ts_job_a1b2c3d4e5f6/result \
  -H "X-API-Key: tsk_..."

GET /api/toxscreen/v1/jobs/{id}/report.{format}

Download a report for a completed job. Accepts X-API-Key or session JWT (Bearer). format options:

• report.pdf — Standalone PDF with per-target risks, CIs, ADMET flags
• report.xlsx — Excel workbook: Summary + Per-Target (with 80%/95% CIs) + ADMET + Extended ADMET
• report.csv — CSV: one row per compound with all scores and extended ADMET endpoints

Example request (PDF)

curl -O https://toxscreen.ai/api/toxscreen/v1/jobs/ts_job_a1b2c3d4e5f6/report.pdf \
  -H "X-API-Key: tsk_..."

Session clients (browser) can still use /jobs/{id}/report (HTML) or /jobs/{id}/report.pdf with a Bearer token.

POST /api/toxscreen/v1/screen/batch

Submit up to 100 compounds as a JSON array for batch screening. Each compound is scored inline (CPU) and is already complete on return. Accepts X-API-Key or session JWT (Bearer). For CSV file upload, use the legacy POST /jobs/batch-upload (multipart form; Pro/Enterprise).

Parameters (JSON body)

Example request

curl -X POST https://toxscreen.ai/api/toxscreen/v1/screen/batch \
  -H "X-API-Key: tsk_..." \
  -H "Content-Type: application/json" \
  -d '{"compounds": [{"smiles": "CCO", "name": "ethanol"}, {"smiles": "c1ccccc1", "name": "benzene"}]}'

Example response

{
  "submitted": 48,
  "failed": 1,
  "failed_jobs": [
    {"name": "lead-077", "smiles": "C1=CC=CC=C1..."}
  ],
  "invalid_rows": [
    {"row": 12, "smiles": "INVALID", "reason": "invalid SMILES"},
    {"row": 37, "reason": "empty SMILES"}
  ],
  "jobs": [
    {"name": "lead-001", "smiles": "CCO", "job_id": "ts_job_a1b2c3d4e5f6"}
  ],
  "credits_used": 48
}

invalid_rows lists rows rejected before scoring (bad/empty SMILES; row is 1-based incl. header). failed_jobs lists valid compounds whose inline scoring failed. jobs contains the created job IDs.

GET /api/toxscreen/queue

View current active-job counts. Public — no authentication required. Because scoring is synchronous (inline CPU), these counts are normally zero.

Example request

curl https://toxscreen.ai/api/toxscreen/queue

Example response

{
  "queued": 0,
  "running": 0,
  "total_active": 0,
  "eta_minutes": 0
}

POST /api/toxscreen/smiles/preview

Validate a SMILES string and preview its molecular properties (2D SVG, MW, LogP, QED, etc.) before submitting a screening job. Public — no authentication required; an RDKit-only call with no DB writes.

Example request

curl -X POST https://toxscreen.ai/api/toxscreen/smiles/preview \
  -H "Content-Type: application/json" \
  -d '{"smiles": "COc1ccc(CCN2CCC(CC2=O)c3ccc(F)cc3)cc1"}'

Example response

{
  "valid": true,
  "canonical": "COc1ccc(CCN2CCC(CC2=O)c3ccc(F)cc3)cc1",
  "svg": "<svg ...>...</svg>",
  "mw": 355.4,
  "logp": 3.2,
  "tpsa": 38.8,
  "hbd": 0,
  "hba": 3,
  "rot_bonds": 5,
  "qed": 0.812,
  "lipinski_violations": 0
}

An invalid SMILES returns {"valid": false, "error": "..."}.

GET /api/toxscreen/calibration

Retrieve current per-target calibration benchmarks (AUROC, class separation, positive/negative counts, pass/fail status) from the latest random-split validation run. Used by the landing-page validation strip and methodology page.

Example request

curl https://toxscreen.ai/api/toxscreen/calibration

Example response

{
  "calibration_date": "2026-06-10",
  "targets": [
    {"pdb": "7CN1", "name": "hERG",   "auc_roc": 0.69, "separation": null, "n_positive": 875, "n_negative": 925,  "status": "FAIL"},
    {"pdb": "6MA7", "name": "CYP3A4", "auc_roc": 0.95, "separation": null, "n_positive": 727, "n_negative": 1073, "status": "PASS"},
    {"pdb": "4WNT", "name": "CYP2D6", "auc_roc": 0.94, "separation": null, "n_positive": 381, "n_negative": 1419, "status": "PASS"},
    {"pdb": "1OG5", "name": "CYP2C9", "auc_roc": 0.94, "separation": null, "n_positive": 671, "n_negative": 1129, "status": "PASS"}
  ]
}

Public — no authentication required. These auc_roc values are in-distribution only (random split of the same TDC data ADMET-AI trained on). CYP3A4 / CYP2D6 / CYP2C9 reach AUROC 0.94–0.95 in-distribution, but an independent novel-chemistry test found CYP3A4 and CYP2C9 AUROC indistinguishable from chance (0.47 and 0.54); CYP2D6 was inconclusive. hERG is the only endpoint with a validated novel-chemistry number (0.69 random split, ~0.84 calibrated) — see the Methodology page for the full de-leak writeup. ToxScreen calibrates conservatively and abstains when a compound falls outside the model's applicability domain. The separation field is reported when available.

GET /api/toxscreen/v1/notifications/test

Fire a test notification to all configured channels (email and/or Slack). Requires auth. Returns whether the test was attempted and which channels were active. Useful for confirming notification settings before a long batch run.

Example request

curl https://toxscreen.ai/api/toxscreen/v1/notifications/test \
  -H "X-API-Key: tsk_..."

Example response

{
  "attempted": true,
  "email_channel": true,
  "slack_channel": false,
  "note": "test notification dispatched"
}

If attempted is false, no channels are configured — enable email or add a Slack webhook in the Settings panel first.

GET /api/toxscreen/billing/plans

List available subscription plans, pricing, and feature breakdowns.

Example request

curl https://toxscreen.ai/api/toxscreen/billing/plans

Example response

{
  "plans": [
    {"tier": "trial",      "name": "Free Trial",  "price_usd": 0,   "screenings": 3,  "features": ["4-target CTI safety panel", "Extended ADMET panel (15+ endpoints)", "HTML + PDF + Excel + JSON reports", "No credit card"]},
    {"tier": "starter",    "name": "Starter",     "price_usd": 49,  "screenings": 10, "features": ["4-target CTI safety panel", "Extended ADMET panel (15+ endpoints)", "HTML + PDF + Excel + JSON reports", "API key access"]},
    {"tier": "pro",        "name": "Pro",         "price_usd": 149, "screenings": 50, "features": ["4-target CTI safety panel", "Extended ADMET panel", "HTML + PDF + Excel + JSON reports", "API key + webhooks", "Batch CSV upload", "Projects & CRO worklist", "SAR trend tracking"]},
    {"tier": "enterprise", "name": "Enterprise",  "price_usd": 999, "screenings": -1, "features": ["Everything in Pro", "Unlimited screenings", "API key + webhooks", "CRO worklist export", "Dedicated support"]}
  ]
}

This endpoint is unauthenticated and used by the public pricing section.