Queue API

Every call is asynchronous. Submitting creates a request; you follow it until it ends, then read its result.

Endpoints

Method and path	Purpose
POST /v1/run/{ns}/{model}/{endpoint}[@version]	Submit. Returns 202 with the request. The bare model aliases interpret.
GET /v1/requests/{id}	Status, stage and, once succeeded, the result in output
GET /v1/requests/{id}/events	Server-sent events for stages; Last-Event-ID resumes
POST /v1/requests/{id}/cancel	Cancel (202; 409 if already finished)
GET /v1/requests/{id}/artifacts/{name}	DICOM SR/SEG, overlays, PDF, FHIR (redirects to a short-lived signed URL)
GET /v1/requests	History with model, status, key and since filters, cursor paging

The API host is https://api.medrun.ai. A fal-compatible queue lives at https://queue.medrun.ai/{ns}/{model}/{endpoint} with the usual …/requests/{id}/status, …/status/stream, …/requests/{id} and …/cancel paths.

Submit body

{
  "input": {
    "files": ["file_01K6…"],
    "prior_files": [],
    "clinical_context": { "age_years": 64, "sex": "male", "indication": "chest pain" },
    "options": { "report": false }
  },
  "webhook": { "url": "https://example.org/medrun", "events": ["request.succeeded", "request.failed"] },
  "priority": "normal",
  "metadata": { "case": "cathlab-2" }
}

input is validated against the endpoint's own schema (see the model's API tab). Pin a version with @1.0.0; every result echoes the version that ran.

Statuses

queued → preparing → running, ending in succeeded, failed, canceled, rejected (the input was refused, for example no usable cine runs) or expired (results purged).

Events

Event	Data
status	Status transitions
stage	{name, label, progress, eta_s}: received, validating, queued_gpu, starting, preprocessing, inference.<step>, postprocessing, uploading, reporting, completed
triage	Critical flags, sent as soon as they are known
partial	Preview artifacts (for example a key-frame overlay)
error	A failure or rejection, followed by done
done	The final request, whatever its status

Idempotency

Send Idempotency-Key (up to 255 characters) on any POST. Replaying the same key and body returns the original response with Idempotent-Replayed: true; the same key with a different body returns 422.