Lean · production · documentation preview

Aroga Enterprise API integration guide

Documentation preview. Analysis is disabled on these documentation hosts. Runtime configuration, signed clinical and data approvals, and hosted synthetic acceptance must be completed before client processing is enabled. This guide describes the implemented gateway contract; it is not a notice that the API is live or approved for patient use.

Hosts and access

The planned documentation hosts are aroga.api.nextgenerationmedicine.co for Detailed, aroga-lean.api.nextgenerationmedicine.co for Lean, and aroga-sandbox.api.nextgenerationmedicine.co for the synthetic sandbox preview. Sandbox is an environment, not a third report tier. These hostnames are not operational client analysis base URLs in this preview.

Client requests use the official NGM website gateway after NGM enables the account and its approved routes:

Append the operation path to that base URL, including its /api prefix. The selected service slug determines the tier. Do not switch tiers while retrying a run. A future custom-domain API mapping requires a separate routing change and acceptance check; do not replace the gateway base URL with a preview hostname. There is no public aroga-sandbox gateway slug in this contract. NGM must confirm the approved sandbox routing for your account before synthetic API testing.

Authentication and effective scope

Use the ngm_dev_ developer key issued for your enabled Aroga enterprise account:

Authorization: Bearer ngm_dev_<your-issued-key>
Content-Type: application/json

Keep the key on your backend. Do not place it in browser JavaScript, source control, URLs, support messages or logs. Upload and download links are temporary credentials and need the same protection. Revoked or invalid keys return HTTP 401; an authenticated account without Aroga access returns HTTP 403.

The current key model has no OAuth scopes or user-selectable per-operation scopes. Its effective access is the five-operation allowlist below, the enabled account's entitlement, and that account's own jobs and objects. Keys belonging to the same account share allowances and ownership. NGM manages the gateway-to-engine credentials and identity; clients must not supply an engine service credential or an identity override.

Other engine routes, multipart upload, cancellation, generic report rewriting and sharing are outside this public gateway contract. Stopping polling does not cancel the analysis.

Synthetic quick start

The following examples are synthetic and are for an explicitly enabled sandbox only. They contain no real patient information. Replace placeholders on your backend after NGM confirms access. Do not run them against a production-routed account as a readiness test.

export AROGA_BASE='https://www.nextgenerationmedicine.co/api/developer/v1/aroga'
export AROGA_KEY='ngm_dev_<your-issued-key>'
export REQUEST_KEY='82a4e6ce-6dda-41c0-91af-4111515476de'

curl --request POST "$AROGA_BASE/api/pipeline/start" \
  --header "Authorization: Bearer $AROGA_KEY" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $REQUEST_KEY" \
  --data '{"inputs":{"input_0":"SYNTHETIC TEST ONLY. Adult age 40. Glucose: 5.0 mmol/L. No other clinical data supplied.","patient_reference":"SYNTH-AROGA-001","clinician":{"physician_name":"Synthetic Reviewer","practice":"Synthetic Test Practice"}}}'

An accepted response is HTTP 200 with a UUID task ID. It confirms admission, not completion or clinical approval:

{"taskId":"dd42b5c1-2e98-43f0-9972-11737f3294f1","status":"started","pipeline_id":"aroga-screening-detailed"}

Persist the task ID, request key, tier and original request before clearing your local pending state. The gateway may include additional provenance and stage fields. Never depend on replayed being present: a saved gateway receipt may omit it.

Optional file upload

Request an upload URL using a neutral synthetic filename:

curl --request POST "$AROGA_BASE/api/files/presign-upload" \
  --header "Authorization: Bearer $AROGA_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"name":"synthetic-labs.pdf","mimeType":"application/pdf","size":2048}'

The response contains uploadUrl, key, fileId and expiresIn (900 seconds). PUT the actual bytes to uploadUrl using the same Content-Type. Do not send the NGM developer key to the object store. Check the PUT succeeds before starting the analysis. Include the returned opaque key verbatim in the start request:

{"inputs":{"input_0":"SYNTHETIC TEST ONLY. Use the attached synthetic lab document.","patient_reference":"SYNTH-AROGA-001"},"file_keys":["<key-returned-by-presign-upload>"]}

Do not construct object keys or copy one between accounts, tiers or environments. Use top-level file_keys; the engine also accepts inputs.file_keys, which takes precedence when both are provided. Avoid sending both forms. The public gateway does not provide a file-list operation.

Start request fields

Supply useful clinical input or uploaded clinical documents. A syntactically accepted request does not guarantee sufficient clinical information or a validated report. Use only the data approved for the workflow; omit identifiers not needed for analysis. There is no automatic patient-name extraction in the Aroga website flow. The coded reference is preserved through report saving.

Idempotency and uncertain outcomes

Send Idempotency-Key on every start and recovery request. A new UUID is recommended for each intentionally new analysis. The gateway accepts 16–128 characters from A–Z, a–z, 0–9, _ and -. Persist the key before the first request and use the same key, exact original payload, file keys and tier on all retries. Reusing a key with a different payload or tier returns HTTP 409 idempotency_conflict.

A timeout or HTTP 502/503 may mean that admission succeeded but the response was lost. HTTP 409 start_outcome_pending also means the result is uncertain. Do not create a new key to work around these responses. Use the read-only recovery operation:

curl "$AROGA_BASE/api/pipeline/recover" \
  --header "Authorization: Bearer $AROGA_KEY" \
  --header "Idempotency-Key: $REQUEST_KEY"

A known job returns HTTP 200 with taskId, status and pipeline_id. An unresolved lookup returns HTTP 409 start_outcome_pending; it does not prove that no job was created. Respect Retry-After or retry_after_seconds, use bounded backoff, and contact NGM if the outcome stays unknown. Recovery does not reserve another analysis or invoke a provider.

The gateway can replay a recorded admission receipt. Automatic resubmission of an uncertain start is limited to 24 hours and the original UTC calendar month; afterward it returns HTTP 409 recovery_expired. Read-only recovery remains available while the engine job exists. Do not reuse old request keys, even after job expiry. Have NGM reconcile an unresolved admission before intentionally starting a replacement analysis.

Poll and interpret the result

curl "$AROGA_BASE/api/pipeline/status/dd42b5c1-2e98-43f0-9972-11737f3294f1" \
  --header "Authorization: Bearer $AROGA_KEY"

Poll with a delay, normally at least 3 seconds for a single job, and back off when instructed. Account-wide traffic, including polling, counts toward the request limit. Status is running, completed or failed. Running responses may provide stage, stageIndex and totalStages; stage timing is not an SLA.

On completion, require a nonempty result.output_0 (Markdown) and result.Visual_Report (HTML). The response also carries the full validation object and version metadata. A completed flag or version-only fragment is insufficient: retain the task ID and recover/contact support if either report body is missing. Do not start another analysis merely to recover a missing report.

{"passed":false,"errors":["required_heading_missing"],"warnings":["unmapped_biomarkers"]}

This example is a validation object, not a complete status response. validation.passed: false requires review and must remain visible in your UI. Missing validation is unknown, never a pass. Preserve both errors and warnings as diagnostic codes; do not turn them into claims of clinical correctness. Even passed: true means automated template/rule validation, not physician sign-off. Every report remains a draft for physician review before patient delivery.

Retain pipeline_id, template_id, template_version, ranges_version and guidelines_version from the returned result with the original task ID. Do not hard-code version values or infer them from the hostname. Treat the output as sensitive clinical content. Render report HTML in an isolated, restricted viewer and preserve the supplied safety notices. Generic AI refine/restyle and public report sharing are disabled in the Aroga website workflow. PDF export there uses an A4 Aroga profile with its report notice and no generic footer; this five-operation API does not expose a PDF-generation route.

Download completed artifacts

curl "$AROGA_BASE/api/reports/dd42b5c1-2e98-43f0-9972-11737f3294f1" \
  --header "Authorization: Bearer $AROGA_KEY"

The response is { "jobId": "...", "reports": [...] }. Each report entry contains key, type, size, lastModified and signedUrl. The stored types are output_0 (Markdown), Visual_Report (HTML), panel (JSON) and meta (JSON). Completion is recorded after all four artifacts are persisted and verified. Download links expire within one hour; request fresh links while the job is accessible. These links do not require the developer bearer key when downloaded and must not be published.

Limits and retention

These are current implementation limits, subject to account configuration and release acceptance. They are not a promise of hosted availability or an agreed commercial allowance.

Detailed and Lean request/start/concurrency limits share the authenticated principal when the required shared database is configured. The website and all developer keys for an account share its monthly admissions. A replay does not reserve another monthly slot or new-start/concurrency slot, but still counts as a request. Rejected or uncertain reserved admissions can count toward the monthly allowance; a failed report does not imply an automatic refund.

Allowed upload MIME types are PDF, JPEG, PNG, GIF, WebP, plain text, CSV and XLSX. The presign endpoint validates the declared size; do not assume it replaces client-side byte-size validation or establishes a tested storage-enforced upload ceiling.

Seven-day job access and the intended 30-day object expiry are separate. Keeping a private object longer does not extend the public job lookup window. The retention worker and its monitoring have not been certified on the hosted deployment by this documentation preview. Confirm the active schedule, scope and retention agreement before any patient use. The object expiry does not establish deletion periods for separately saved website records or customer-held copies.

Errors and retry decisions

The error envelope normally has an error code; framework errors may also contain statusCode or message. Do not log raw inputs, reports or provider error text to diagnose failures. Share only the task ID, request key, tier, timestamp and safe error code through the agreed support channel.

Release acceptance

Before enabling a client account, NGM must verify account entitlements and dedicated routing, gateway key issuance/revocation, approved clinical policy and data agreements, runtime readiness, isolated synthetic upload/start/replay/recovery/download, restart recovery, shared limits, clinician review presentation and the hosted retention schedule. The public documentation preview and its health endpoint certify only that documentation can be served. They do not verify analysis readiness or authorize clinical use.