API Reference

Base URL: https://biotradingarena.com

Public Endpoints

These endpoints do not require authentication.

GET /api/catalysts

Returns all 645 catalyst cases.

GET /api/oncology

Returns oncology-specific cases (369 cases).

GET /api/strategies

Returns available prediction strategies.

GET /api/pubmed/:pmid

Fetches a PubMed article by PMID, including abstract and full paper text when available.

No authentication required — PubMed data is public.

Full text is fetched from PubMed Central (PMC) for open access articles. For papers with a DOI but no PMC entry, an open access URL is returned via Unpaywall when available.

Response:

{
  "pmid": "40910168",
  "title": "Characterization and Application of Novel Exercise Recovery Patterns...",
  "abstract": "Post-exercise oxygen uptake recovery (VO2Rec) is slow in...",
  "full_text": "## What Is New?\n\nThis study reports multiple novel measures...",
  "full_text_source": "pmc",
  "journal": "Circulation",
  "pubdate": "2025 Oct 7",
  "doi": "10.1161/CIRCULATIONAHA.124.073585",
  "pmc_id": "PMC12493091",
  "pubmed_url": "https://pubmed.ncbi.nlm.nih.gov/40910168/",
  "authors": ["Campain J", "Griskowitz C", "Newlands C"],
  "has_full_text": true
}

Field	Type	Description
`full_text`	string\|null	Full paper text from PMC, or OA link from Unpaywall, or null
`full_text_source`	string\|null	`"pmc"`, `"unpaywall"`, or null
`has_full_text`	boolean	Whether actual full text content is available

GET /api/catalysts/:id/papers

Returns all PubMed papers linked to a catalyst, enriched with abstracts and full text.

No authentication required.

Query Parameters:

Parameter	Type	Default	Description
`full_text`	string	`"true"`	Set to `"false"` to skip PMC full text fetching (faster)

Response:

{
  "catalyst_id": "CYTK_2025-12-19_MYQORZO",
  "ticker": "CYTK",
  "drug": "MYQORZO (aficamten)",
  "paper_count": 5,
  "full_text_count": 3,
  "papers": [
    {
      "pmid": "40910168",
      "title": "Characterization and Application of Novel Exercise Recovery...",
      "journal": "Circulation",
      "pubdate": "2025 Oct 7",
      "doi": "10.1161/CIRCULATIONAHA.124.073585",
      "pmc_id": "PMC12493091",
      "abstract": "Post-exercise oxygen uptake recovery...",
      "full_text": "## What Is New?\n\nThis study reports...",
      "full_text_source": "pmc",
      "has_full_text": true
    }
  ]
}

Benchmark Endpoints

These endpoints require authentication via Authorization: Bearer <api_key>.

GET /api/benchmark/cases

Fetch benchmark cases with all input data for evaluation.

Query Parameters:

Parameter	Type	Default	Description
`subset`	string	`oncology`	`oncology`, `non_oncology`, or `all`
`limit`	integer	all	Max cases (up to 1000)
`offset`	integer	`0`	Pagination offset

Response:

{
  "total": 369,
  "count": 369,
  "subset": "oncology",
  "impact_categories": ["very_negative", "negative", "slightly_negative", "neutral", "slightly_positive", "positive", "very_positive"],
  "cases": [...]
}

POST /api/benchmark/verify

Score your predictions without saving them. Returns detailed per-case results.

Request Body:

{
  "predictions": [
    {
      "case_id": "onc_0001",
      "predicted_impact": "positive",
      "confidence": 0.85
    }
  ]
}

Field	Required	Description
`predictions`	Yes	Array of predictions (max 1000)
`predictions[].case_id`	Yes	Case identifier
`predictions[].predicted_impact`	Yes	One of the 7 impact categories
`predictions[].confidence`	No	Confidence score (0-1)
`predictions[].reasoning`	No	Your model's reasoning

Response:

{
  "metrics": {
    "cases_evaluated": 369,
    "exact_match_accuracy": 28.5,
    "directional_accuracy": 62.3,
    "close_accuracy": 55.0,
    "avg_confidence": 0.72
  },
  "direction_confusion_matrix": {
    "positive": { "positive": 45, "neutral": 5, "negative": 2 },
    "neutral": { "positive": 8, "neutral": 12, "negative": 6 },
    "negative": { "positive": 3, "neutral": 7, "negative": 35 }
  },
  "results": [
    {
      "case_id": "onc_0001",
      "predicted_impact": "positive",
      "actual_impact": "positive",
      "percent_change": 12.5,
      "exact_match": true,
      "close_match": true,
      "direction_correct": true
    }
  ]
}

POST /api/benchmark/submit

Submit predictions to the leaderboard. Predictions are scored and saved.

Request Body:

{
  "strategy_name": "My Strategy v1",
  "description": "Brief description of approach",
  "model": "gpt-4o",
  "predictions": [
    {
      "case_id": "onc_0001",
      "predicted_impact": "positive",
      "predicted_score": 12.0,
      "confidence": 0.85
    }
  ]
}

Field	Required	Description
`strategy_name`	Yes	Name for your strategy (max 100 chars)
`description`	No	Description (max 500 chars)
`model`	No	Model name (max 100 chars)
`predictions`	Yes	Array of predictions (max 1000)
`predictions[].case_id`	Yes	Case identifier
`predictions[].predicted_impact`	No*	Categorical prediction
`predictions[].predicted_score`	No*	Numeric % change prediction
`predictions[].confidence`	No	Confidence score (0-1)

*At least one of predicted_impact or predicted_score is required per prediction.

Response:

{
  "submission_id": "sub_abc123_xyz789",
  "strategy_name": "My Strategy v1",
  "submitted_by": "user@example.com",
  "cases_evaluated": 369,
  "metrics": {
    "exact_match_accuracy": 28.5,
    "directional_accuracy": 62.3,
    "close_accuracy": 55.0,
    "avg_confidence": 0.72,
    "mae": 8.45
  },
  "leaderboard_rank": 3,
  "total_submissions": 12,
  "message": "Submission accepted! Your strategy ranks #3 out of 12 on the leaderboard."
}

Error Codes

Status	Meaning
`400`	Bad request — invalid or missing fields
`401`	Unauthorized — missing or invalid API key
`500`	Internal server error
`503`	Auth not configured on the server

API Reference

On this page