Aroga Biomarker Analysis API sandbox: integration guide

How to call the Aroga Biomarker Analysis API sandbox.

1. Base URL and authentication

Base URL: https://aroga-sandbox.nextgenerationmedicine.co

Send your API key as a Bearer token on every /api/* request:

Authorization: Bearer <your api key>

Three pages need no key: GET /health, GET /docs (this guide) and GET /api-json (the OpenAPI document).

Upload links and report links work without the header. Keep them secret.

Errors are JSON:

{
  "statusCode": 400,
  "error": "validation_failed",
  "message": "One or more inputs are invalid.",
  "fields": ["inputs.patient.age: must be an integer between 18 and 120"]
}

statusCode is the HTTP status, error is a stable code, message is for people, and fields is present when single fields are at fault.

2. Quick start

BASE=https://aroga-sandbox.nextgenerationmedicine.co
KEY=<your api key>

# 1. Ask for an upload link
curl -s -X POST "$BASE/api/files/presign-upload" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"labs.pdf","mimeType":"application/pdf","size":78042}'
# {"uploadUrl":"<uploadUrl>","key":"aroga/sandbox/uploads/<fileId>.pdf","fileId":"<fileId>","expiresIn":900}

# 2. Upload the file bytes to uploadUrl (no Authorization header)
curl -s -X PUT "<uploadUrl>" -H "Content-Type: application/pdf" --data-binary @labs.pdf
# {}

# 3. Start the report
curl -s -X POST "$BASE/api/pipeline/start" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"idempotency_key":"case-0042-2026-03-16","inputs":{"report_type":"general_practice","patient":{"name":"Patient 1","age":47,"sex":"female"},"files":[{"file_key":"aroga/sandbox/uploads/<fileId>.pdf","kind":"labs","collected_on":"2026-03-16"}]}}'
# {"taskId":"<taskId>","status":"started", ...}

# 4. Poll every 15 to 30 seconds until status is completed, held or failed
curl -s "$BASE/api/pipeline/status/<taskId>" -H "Authorization: Bearer $KEY"

# 5. List the report files, then download one with its report link
curl -s "$BASE/api/reports/<taskId>" -H "Authorization: Bearer $KEY"
curl -s "<signedUrl>" -o output_0.md

3. Requests

Upload a lab file

POST /api/files/presign-upload

{ "uploadUrl": "https://aroga-sandbox.nextgenerationmedicine.co/api/files/upload/<upload link id>", "key": "aroga/sandbox/uploads/<fileId>.pdf", "fileId": "<fileId>", "expiresIn": 900 }

PUT <uploadUrl> with the file bytes as the body and no Authorization header. At most 4 MB, and the bytes must be of the type given in mimeType. Success is 200 with {}. The link works for 15 minutes and can be used again until then; each upload replaces the file. Pass key, exactly as returned, as file_key in an inputs.files entry.

POST /api/files/upload is the one-step alternative: multipart/form-data, field files, up to 10 files and 4 MB in total. Response 201:

{ "message": "1 file(s) uploaded successfully", "files": [{ "fileId": "<fileId>", "name": "labs.pdf", "key": "aroga/sandbox/uploads/<fileId>.pdf", "mimeType": "application/pdf", "size": 78042 }] }

DELETE /api/files/{key} deletes a file you uploaded. Send the key as it is, or with its slashes percent-encoded (%2F). The response is always 200:

{ "deleted": true, "message": "File deleted", "key": "aroga/sandbox/uploads/<fileId>.pdf" }

GET /api/files/list, GET /api/files/signed-url/{key} and GET /api/files/download/{key} return 501 not_supported.

Start a report

POST /api/pipeline/start

{
  "idempotency_key": "case-0042-2026-03-16",
  "inputs": {
    "report_type": "general_practice",
    "patient": { "name": "Patient 1", "age": 47, "sex": "female", "birth_year": "1978", "height_cm": 165, "weight_kg": 77.4, "fasting_confirmed": true },
    "files": [
      { "file_key": "aroga/sandbox/uploads/<fileId>.pdf", "kind": "labs", "collected_on": "2026-03-16" },
      { "file_key": "aroga/sandbox/uploads/<fileId>.pdf", "kind": "labs", "collected_on": "2025-03-12" },
      { "inline": { "name": "visit.txt", "mime_type": "text/plain", "raw_bytes": "<base64>" }, "kind": "encounter_notes" },
      { "file_key": "aroga/sandbox/uploads/<fileId>.pdf", "kind": "body_composition", "collected_on": "2026-03-16" }
    ],
    "context": { "medications": ["Ramipril 5 mg daily"], "devices": ["Hormonal IUD (levonorgestrel)"], "conditions": ["Hypertension"], "allergies": ["Penicillin (rash)"] },
    "clinician_notes": "<free text from the clinician>",
    "care_team_notes": [{ "role": "nutritionist", "written_on": "2026-02-10", "text": "<the nutritionist's note>" }],
    "plan_exclusions": ["fasting"],
    "overall_instructions": "<your instruction package>"
  }
}

Top level: inputs (required) and idempotency_key (optional, at most 200 characters, see section 6).

inputs:

Fields that are not listed here are accepted and ignored. A request that sends member, input_0, file_keys or Other_files is answered with 400 contract_changed, and its fields name what to send in their place.

patient:

Each entry of files:

Send each lab report as its own file of kind labs, earlier reports included, with its collected_on. Each lab file is read on its own, so lab_results holds every test by the date of its own report. Encounter notes and a Molecular You report, as PDF, image or text, are read on their own too, and the report summarizes them.

A body composition report and the report of an ECG, treadmill test, spirometry or chest X-ray are read on their own as well. The report shows body composition values and classification as printed, and each test's conclusion as reported, without the test report's recommendations. Send the date of the measurement or test as collected_on.

Each entry of care_team_notes:

The report builds on the care team's notes and never contradicts them. It shows its own points from them, not the notes themselves.

plan_exclusions takes distinct ids from this switch table. The report suggests nothing an excluded id covers, anywhere:

Response 200:

{
  "taskId": "0f8c2e1a-5b7d-4e2a-9c31-7a1d2b3c4d5e", "status": "started",
  "pipeline_id": "aroga-biomarker-analysis", "environment": "sandbox", "totalStages": 4,
  "template_id": "aroga-biomarker-analysis", "template_version": "v1.1.0", "ranges_version": "draft-2026-09-29", "build": "82ad61c"
}

status is existing when the request repeated an idempotency_key. A start with overall_instructions also carries instructions_sha256, as the task status does.

4. Responses

Task status

GET /api/pipeline/status/{taskId}

{
  "status": "running", "completed": false,
  "stage": "Writing", "stageIndex": 2, "totalStages": 4,
  "pipeline_id": "aroga-biomarker-analysis", "report_type": "general_practice", "environment": "sandbox",
  "template_id": "aroga-biomarker-analysis", "template_version": "v1.1.0", "ranges_version": "draft-2026-09-29", "build": "82ad61c",
  "created_at": "2026-10-02T15:04:05.000Z", "updated_at": "2026-10-02T15:07:41.000Z", "expires_at": "2026-11-01T15:04:05.000Z",
  "progress": { "message": "Working on the report", "elapsed_seconds": 216 }
}

A failed task:

{
  "status": "failed", "completed": false, "stage": "Writing", "stageIndex": 2, "totalStages": 4,
  "error": "The run exceeded its time limit and was stopped. Start a new run.", "error_category": "deadline_exceeded",
  "progress": { "message": "Stopped", "elapsed_seconds": 1741 }
}

error is a sentence. error_category is deadline_exceeded, input_rejected or pipeline_error.

A held task is final, like a completed one, and carries validation and result: the report was produced, but a check still found an error after one rewrite. validation.errors lists what held it. Show the report only after clinician review.

A completed task carries validation and result:

{
  "status": "completed", "completed": true, "stage": "Quality checks", "stageIndex": 4, "totalStages": 4,
  "validation": { "passed": true, "errors": [], "warnings": [] },
  "result": {
    "report_type": "general_practice",
    "output_0": "Aroga Lifestyle Medicine\n\n*Your health assessment*\n\n# Aroga Biomarker Report\n\n...",
    "Visual_Report": "<!doctype html>...",
    "outputs": { "markdown": true, "html": true, "pdf": true },
    "validation": { "passed": true, "errors": [], "warnings": [] },
    "panel": {
      "ranges_version": "draft-2026-09-29",
      "categories": [{
        "key": "nutrients-iron-status", "name": "Nutrients & Iron Status",
        "rows": [{
          "key": "vitamin-d-25-oh-total-ia", "display_name": "Vitamin D, 25-OH, Total, IA",
          "value": 21, "value_text": "21", "unit": "ng/mL",
          "reference_range": { "lo": 60, "hi": 80 }, "reference_range_text": "30-100 ng/mL (optimal 60-80)",
          "lab_range": { "lo": 30, "hi": 100 }, "lab_range_text": "30-100 ng/mL",
          "lab_flag": "L", "target": "optimal 60-80", "status": "Below Target", "source": "measured"
        }]
      }]
    },
    "lab_results": {
      "catalog_version": "labs-2026-10-06.1", "dates": ["2025-03-12", "2026-03-16"], "current_date": "2026-03-16",
      "analytes": [{
        "key": "apob", "name": "ApoB", "group": "lipids", "specimen": "blood",
        "results": [
          { "collected_on": "2025-03-12", "value": 1.12, "value_text": "1.12", "unit": "g/L", "value_as_printed": "112", "unit_as_printed": "mg/dL", "converted": true, "reference_range": "<90", "lab_flag": "H", "file_index": 1, "found_on_report": true },
          { "collected_on": "2026-03-16", "value": 0.94, "value_text": "0.94", "unit": "g/L", "value_as_printed": "0.94", "unit_as_printed": "g/L", "converted": false, "reference_range": "<1.05", "lab_flag": null, "file_index": 0, "found_on_report": true }
        ]
      }]
    },
    "unmapped_biomarkers": ["OMEGA-3 INDEX"], "regenerations": 0,
    "references": [{ "n": 1, "doi": "10.1000/example", "pmid": "12345678", "title": "..." }],
    "usage": [], "credits": { "report": "0", "visual": "0" },
    "template_id": "aroga-biomarker-analysis", "template_version": "v1.1.0", "ranges_version": "draft-2026-09-29", "build": "82ad61c"
  }
}

Panel row fields: key, display_name, value, value_text, unit, reference_range, reference_range_text, lab_range, lab_range_text, lab_flag, target, status, source.

Lab result fields: collected_on, value, value_text, unit, value_as_printed, unit_as_printed, converted, reference_range, lab_flag, file_index, found_on_report. unit is the SI unit, or the unit on the lab file when no single conversion applies. reference_range is as it appears on the lab file. file_index is the position of the file in inputs.files.

A general practice report shows how each result moved across the lab dates within 400 days of the latest, with charts, and groups its plan by Aroga's six pillars. Both report types show the body composition and test tables, and the care team's points when notes were sent.

Validation: passed is false when a check reported an error. errors and warnings are lists of code: message. The report is returned either way. New codes can appear.

Report files

GET /api/reports/{taskId}

{
  "jobId": "0f8c2e1a-5b7d-4e2a-9c31-7a1d2b3c4d5e",
  "reports": [
    { "key": "aroga/sandbox/reports/<taskId>/output_0.md", "type": "output_0", "contentType": "text/markdown", "size": 31874, "lastModified": "2026-10-02T15:12:31.000Z", "signedUrl": "https://aroga-sandbox.nextgenerationmedicine.co/api/reports/<taskId>/files/output_0.md?exp=1791216751&sig=<hex>" },
    { "key": "aroga/sandbox/reports/<taskId>/Visual_Report.html", "type": "Visual_Report", "contentType": "text/html", "size": 58210, "lastModified": "2026-10-02T15:12:31.000Z", "signedUrl": "..." },
    { "key": "aroga/sandbox/reports/<taskId>/Visual_Report.pdf", "type": "Visual_Report_PDF", "contentType": "application/pdf", "size": 41210, "lastModified": "2026-10-02T15:12:31.000Z", "signedUrl": "..." },
    { "key": "aroga/sandbox/reports/<taskId>/meta.json", "type": "meta", "contentType": "application/json", "size": 9120, "lastModified": "2026-10-02T15:12:31.000Z", "signedUrl": "..." }
  ]
}

• Each signedUrl is a report link that works for 1 hour without the Bearer header. Call this endpoint again for fresh links.
• While the task is running the response is 404 with "error": "not_ready".
• A failed task lists meta.json only. Visual_Report.pdf is listed when the PDF could be produced; otherwise a warning in validation says so.

GET /api/reports/{taskId}/files/{name} serves output_0.md, Visual_Report.html, Visual_Report.pdf or meta.json, with a report link or with your Bearer key.

meta.json is the record of the task: its status, report_type, versions, instructions_sha256 when the task was started with instructions, validation, panel, references and, once recorded, its latest review. A failed task has error and error_category in place of validation. /api-json lists every field.

Clinician review

POST /api/reports/{taskId}/review records the review of a completed or held report by the patient's clinician:

{ "decision": "released", "reviewer": "clinician-17", "report_sha256": "<SHA-256 of the file reviewed>", "note": "Read with the lab report." }

Response 200:

{ "taskId": "<taskId>", "review": { "decision": "released", "reviewer": "clinician-17", "reviewed_at": "2026-10-02T16:20:00.000Z", "report_file": "Visual_Report.pdf", "report_sha256": "<hex>", "note": "Read with the lab report." } }

The latest review shows as review in the task status and in meta.json, and the last 20 are kept. Recording one never changes the task: a held task stays held. A running or failed task answers 409 not_reviewable. A report_sha256 that is not the hash of the task's PDF or Markdown answers 409 report_mismatch.

Show a report, completed or held, to the patient only when its latest review has decision released and a report_sha256 that is the SHA-256 of the file shown. A returned report is not shown.

Health

GET /health

{
  "ok": true, "status": "ok", "service": "aroga-biomarker-analysis-api", "client": "aroga", "environment": "sandbox",
  "region": "us-west2", "tier": "standard", "time": "2026-10-02T15:00:00.000Z",
  "template_id": "aroga-biomarker-analysis", "template_version": "v1.1.0", "ranges_version": "draft-2026-09-29", "build": "82ad61c"
}

5. Errors

A 429 carries retry_after_seconds and a Retry-After header.

6. Limits and timing

• Poll every 15 to 30 seconds.
• Stop polling after 33 minutes.
• A 404 on the status route means the task does not exist for your key.

Send idempotency_key on every start. A repeat with the same key and the same API key within 24 hours returns the original taskId with status: "existing" and starts nothing.

A task and its report can be fetched for 30 days. An uploaded file can be used for 7 days. Each is deleted at the first daily sweep after its period ends. A task's reviews are deleted with it.

7. Data rule

• Sandbox is synthetic-data only. Do not send real member data until the BAA is executed.
• patient.name is a display name. Use a placeholder such as Patient 1.
• The files, context, clinician_notes and care_team_notes hold synthetic content only.
• Do not publish upload links or report links.

8. Support

Reply to your NGM contact and include the task id, plus the template_version and build from the response.