API Reference

Base URL: https://biotradingarena.com

Public Endpoints

These endpoints do not require authentication.

GET /api/catalysts

Returns all 413 published cases. Each case exposes whether its source evidence is verified or retained from the legacy reviewed set with disclosed warnings.

GET /api/oncology

Returns 233 oncology-specific cases. Authentication is required.

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

This compatibility endpoint currently returns an empty paper list. Legacy catalyst-to-literature associations were withdrawn because their relevance had not been independently audited.

No authentication required.

Response:

{
  "catalyst_id": "COGT_2025-11-10_bezuclastinib",
  "paper_count": 0,
  "papers": [],
  "message": "Linked literature is unavailable pending independent relevance review."
}

Benchmark Endpoints

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

GET /api/benchmark/cases

Fetch model inputs. Exact event dates, ticker-bearing IDs, NCT IDs, sponsors, price action, and ground truth are excluded.

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": 233,
  "count": 233,
  "subset": "oncology",
  "inputs_only": true,
  "scoring_endpoint": "/api/benchmark/verify",
  "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": "case_0123456789abcdef",
      "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": 233,
    "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": "case_0123456789abcdef",
      "predicted_impact": "positive",
      "actual_impact": "positive",
      "percent_change": 12.5,
      "impact_score": 2.5,
      "exact_match": true,
      "close_match": true,
      "direction_correct": true
    }
  ]
}

POST /api/benchmark/submit

Score predictions and send the run for leaderboard review. The endpoint does not publish a leaderboard row automatically.

Request Body:

{
  "strategy_name": "My Strategy v1",
  "description": "Brief description of approach",
  "model": "gpt-4o",
  "predictions": [
    {
      "case_id": "case_0123456789abcdef",
      "predicted_impact": "positive",
      "predicted_score": 2.4,
      "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 impact-score prediction (-10 to +10)
`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": 233,
  "metrics": {
    "exact_match_accuracy": 28.5,
    "directional_accuracy": 62.3,
    "close_accuracy": 55.0,
    "avg_confidence": 0.72,
    "mae": 8.45
  },
  "message": "Submission received. Your results have been sent for leaderboard review."
}

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