TrialCurve API documentation

One request: send an image of a Kaplan–Meier figure and get back every survival panel's digitised curves, numbers at risk, reconstructed individual patient data (Guyot 2012), hazard ratios, medians and RMST, with checks against the statistics printed on the figure.

Quickstart

Get a key from the pricing page, which includes 3 free credits every month. Then send a figure:

curl https://trialcurve.com/v1/reconstruct \
  -H "Authorization: Bearer $TRIALCURVE_KEY" \
  -F image=@figure2a.png

The response contains every arm's digitised curve, its at-risk table, reconstructed individual patient data (IPD), and summary statistics including hazard ratios. Add -F 'options={"format":"csv"}' to get IPD rows (arm,time,event) instead.

Authentication

Send your key as a bearer token: Authorization: Bearer tc_live_…. Keys are shown once after checkout. To rotate a key, call POST /v1/keys/rotate with the current key. The old key stops working immediately.

POST /v1/reconstruct

Send multipart/form-data with:

Alternatively, send application/json with image_base64 plus the options fields at the top level.

Cost: 1 credit per standard request and 3 credits in audit mode. Failed requests (4xx/5xx) are not billed.

Options & hints

{
  "mode": "standard" | "audit",        // audit reads at the highest model effort (3 credits)
  "format": "json" | "csv",            // csv returns IPD rows: arm,time,event
  "overlay": false,                     // include a PNG (base64) of the reconstruction drawn over the figure
  "hints": {
    "arm_names": ["Placebo", "Drug"],  // override names, in the order the arms are returned
    "n_arms": 2,                        // if the figure has no at-risk table
    "at_risk": {                        // type the table yourself if the image doesn't include it
      "times": [0, 6, 12, 18],
      "counts": [[150, 120, 90, 60], [148, 130, 110, 91]]
    },
    "n_per_arm": [150, 148],            // no table: reconstruct from initial N (less accurate)
    "total_events": [101, 80],          // improves the final interval when reported in the paper
    "reference_arm": "Placebo",         // HR reference (name or index); default = arm with lowest RMST
    "y_percent": true                   // force the y scale if the labels are unreadable
  },
  "published": {                        // values reported in the paper, checked against the reconstruction
    "hazard_ratio": 0.72, "hr_arm": "Drug", "hr_reference": "Placebo",
    "arms": { "Drug": { "n": 148, "median": 14.2, "events": 80 } }
  }
}

Response

The top-level fields describe the first survival panel. A whole figure can hold several, so every panel is also returned in panels, each with the same fields plus what the figure printed and how the reconstruction compares with it.

{
  "id": "req_…",
  "panels": [{                                  // one entry per survival panel in the figure
    "panel": { "label": "A", "endpoint": "Overall survival", "population": "Intention-to-treat",
               "curve_source": "vision_model" | "pixel_measurement_confirmed_by_vision_model",
               "plotted": "survival" | "cumulative_incidence" },
    "arms": [ … ], "comparisons": [ … ],        // as below
    "printed_statistics": { "hazard_ratios": [ … ], "medians": [ … ], "event_counts": [ … ] },
    "printed_value_checks": [{
      "item": "hazard ratio", "printed": 0.72, "reconstructed": 0.735, "relative_difference": 0.021,
      "status": "pass" | "flag",
      "role": "validation" | "consistency",    // N and printed event counts feed the reconstruction
      "direction": "printed" | "inferred",     // was the comparison's direction stated on the figure?
      "printed_ci95": [0.60, 0.86], "within_printed_ci": true,
      "second_reading_agrees": true            // present when a second, larger model re-read a flagged figure
    }],
    "quality": { … }, "warnings": [ … ]
  }],
  "reader": { "model": "claude-opus-5-5", "effort": "high", "zoom": true, "escalated": false, "attempts": [ … ] },
  "arms": [{
    "name": "Pembrolizumab", "color": "#00bfc4",
    "curve": { "time": [0, 0.41, …], "survival": [1, 0.996, …] },   // digitised step points
    "censor_marks": [3.1, 7.9, …],
    "at_risk": { "times": [0, 12, 24, 36], "counts": [269, 144, 91, 47] },
    "ipd": { "time": [0.41, …], "event": [1, 0, …] },                // one row per reconstructed patient
    "summary": {
      "n": 269, "events": 229, "median": 14.62,
      "survival_at": { "12": 0.5412, "24": 0.3571 },
      "rmst": { "tau": 58.9, "value": 21.3 },
      "method": "guyot_2012_with_at_risk_table",
      "reconstruction_max_abs_error": 0.0071     // KM(IPD) vs digitised curve
    }
  }],
  "comparisons": [{ "arm": "Pembrolizumab", "reference": "Chemotherapy", "hazard_ratio": 0.68,
                    "ci95": [0.57, 0.81], "wald_p": 1.2e-05, "logrank_p": 1.1e-05, "rmst_difference": 5.1 }],
  "axes": { "x": { "min": 0, "max": 60, "labels_used": 6, "calibration_residual_px": 0.4, "calibration": {…} },
            "y": { "scale": "percent", … } },
  "quality": { "score": 1.0, "grade": "high", "reasons": [] },
  "warnings": [],
  "validation": { "provenance": {…}, "vision_cross_check": {…}, "published_value_checks": […], "ai_use_disclosure": {…}, "overall": {…} },
  "billing": { "units": 1 }
}

Times are in the units of the figure's time axis. Hazard ratios come from a Cox model (Efron ties) fitted to the reconstructed IPD, so they are unstratified; a printed hazard ratio that is stratified or adjusted can differ by a few percent. Cumulative-incidence panels are reconstructed on the 1 − cumulative incidence scale (panel.plotted says which). Always check quality.grade, warnings and the printed_value_checks before using the numbers.

Validation pack

• provenance: engine version, image SHA-256, UTC timestamp, method statement, hints used.
• vision_cross_check: the model's reading of each curve compared with the pixel measurement (max and mean |ΔS| per arm), plus every check against statistics printed on the figure.
• published_value_checks: each value you pass in published (for example from the paper's text) is compared with the reconstruction. Status is pass when the relative difference is within 10% (N must match exactly).
• independent_extraction (measurement-only mode, audit): when the vision model is unavailable, a second digitisation after resampling the image, with per-arm agreement.
• ai_use_disclosure: tool, version, date, developer, model and provider, purpose, prompt hash (the prompt is available on request), a human-oversight note and a suggested statement for JCA/HTA dossiers, following the EU HTA Coordination Group's AI principles.
• overall.status: ready_for_use or review_recommended, with the reasons listed.

Errors

Errors have the shape {"error": {"code": "…", "message": "…"}}.

Usage, keys & billing

• GET /v1/usage: credits used in the current billing period.
• POST /v1/keys/rotate: issues a new key and revokes the old one.
• GET /api/portal: returns a Stripe billing portal URL for invoices, payment method and cancellation.

Getting the best results

• Send the whole figure: multi-panel layouts, inset tables and printed statistics are handled, and every survival panel is returned.
• Use the sharpest copy you have: export the figure from the PDF, or zoom the PDF to 200% before taking a screenshot (text at least ~10 px tall). Images up to 2576 px on the long edge are read at full resolution.
• If curves share a colour and cross, pass arm_names and check the overlay.
• No at-risk table in the paper? Pass n_per_arm and, if reported, total_events. Expect wider error.
• For dossier work use mode: "audit" and pass the reported values in published.

Method & citation

Reading: Claude Opus 5.5 reads the whole figure (every panel's axes, arm names, curves as step corners, numbers-at-risk table and printed statistics), with a zoom tool for small text, steps and overlapping curves. Measurement: each panel the model locates is also traced in pixels (plot-frame detection, tick calibration, colour separation, sub-pixel tracing of each step function); where the two agree, the measured curve is used. Checks: every reconstruction is compared with the hazard ratios, medians and event counts printed on the figure, and a figure that disagrees is re-read by a larger configuration. If the vision model is unavailable, the measurement engine runs alone with on-device OCR, and the response says so. Reconstruction: Guyot P, Ades AE, Ouwens MJNM, Welton NJ. Enhanced secondary analysis of survival data: reconstructing the data from published Kaplan-Meier survival curves. BMC Med Res Methodol 2012;12:9.